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Preface 


This manual provides users of the OpenVMS operating system with detailed 
usage and reference information on library routines supplied in the LIB$ and 
CVT$ facilities of the Run-Time Library. 

Intended Audience 

This manual is intended for system and application programmers who want to 
call Run-Time Library routines. 

Document Structure 

This manual is organized into three parts as follows: 

• The Overview chapter provides a brief overview of the LIB$ Run-Time 
Library facility and lists the LIB$ routines and their functions. It also 
provides guidelines and information on using the LIB$ facility with VAX and 
AXP platforms. 

• The LIB$ Reference Sections describes each library routine contained in 
the LIB$ Run-Time Library facility. This information is presented using 
the documentation format described in OpenVMS Programming Interfaces: 
Calling a System Routine. Routine descriptions appear alphabetically by 
routine name. 

• The CVT$ Reference Sections describes the routine contained in the 
CVT$ Run-Time Library facility. This information is presented using the 
documentation format described in OpenVMS Programming Interfaces: 
Calling a System Routine. 

Associated Documents 

The Run-Time Library routines are documented in a series of reference manuals. 
A description of how the Run-Time Library routines are accessed is presented in 
OpenVMS Programming Interfaces: Calling a System Routine. A description of 
OpenVMS features and functionality available through calls to the LIB$ Run¬ 
Time Library appears in OpenVMS Programming Concepts Manual. Descriptions 
of the other RTL facilities and their corresponding routines are presented in the 
following books: 

• DPML , Digital Portable Mathematics Library 

• OpenVMS RTL DECtalk (DTK$) Manual 

• OpenVMS VAX RTL Mathematics (MTH$) Manual 

• OpenVMS RTL General Purpose (OTS$) Manual 






• OpenVMS RTL Parallel Processing (PPL$) Manual 

• OpenVMS RTL Screen Management (SMG$) Manual 

• OpenVMS RTL String Manipulation (STR$) Manual 

Application programmers using any language can refer to the Guide to Creating 
OpenVMS Modular Procedures for writing modular and reentrant code. 

High-level language programmers will find additional information on calling 
Run-Time Library routines in their language reference manuals. Additional 
information may also be found in the language user’s guide provided with your 
OpenVMS language software. 

For a complete list and description of the manuals in the OpenVMS 
documentation set, see Overview of OpenVMS Documentation. 

Conventions 

In this manual, every use of OpenVMS AXP means the OpenVMS AXP operating 
system, every use of OpenVMS VAX means the OpenVMS VAX operating system, 
and every use of OpenVMS means both the OpenVMS AXP operating system and 
the OpenVMS VAX operating system. 

The following conventions are used to identify information specific to OpenVMS 
AXP or to OpenVMS VAX: 



The AXP icon denotes the beginning of information 
specific to OpenVMS AXP. 


The VAX icon denotes the beginning of information 
specific to OpenVMS VAX. 


The diamond symbol denotes the end of a section of 
♦ information specific to OpenVMS AXP or to OpenVMS 

VAX. 

The following conventions are used in this manual: 

Ctrl/x A sequence such as Ctrl/x indicates that you must hold down 

the key labeled Ctrl while you press another key or a pointing 
device button. 

PF1 x A sequence such as PF1 x indicates that you must first press 

and release the key labeled PF1, then press and release 
another key or a pointing device button. 

GOLD x A sequence such as GOLD x indicates that you must first press 

and release the key defined GOLD, then press and release 
another key. GOLD key sequences can also have a slash (/), 
dash (-), or underscore (_) as a delimiter in EVE commands. 

| Return | In examples, a key name enclosed in a box indicates that 

you press a key on the keyboard. (In text, a key name is not 
enclosed in a box.) 


x 





() 

[] 

{} 

boldface text 

italic text 

UPPERCASE TEXT 

numbers 


A horizontal ellipsis in examples indicates one of the following 
possibilities: 

• Additional optional arguments in a statement have been 
omitted. 

• The preceding item or items can be repeated one or more 
times. 

• Additional parameters, values, or other information can be 
entered. 

A vertical ellipsis indicates the omission of items from a code 
example or command format; the items are omitted because 
they are not important to the topic being discussed. 

In format descriptions, parentheses indicate that, if you 
choose more than one option, you must enclose the choices 
in parentheses. 

In format descriptions, brackets indicate optional elements. 
You can choose one, none, or all of the options. (Brackets are 
not optional, however, in the syntax of a directory name in 
an OpenVMS file specification, or in the syntax of a substring 
specification in an assignment statement.) 

In format descriptions, braces surround a required choice of 
options; you must choose one of the options listed. 

Boldface text represents the introduction of a new term or the 
name of an argument, an attribute, or a reason. 

Boldface text is also used to show user input in Bookreader 
versions of the manual. 

Italic text emphasizes important information, indicates 
variables, and indicates complete titles of manuals. Italic 
text also represents information that can vary in system 
messages (for example, Internal error number ), command lines 
(for example, /PRODUCER=7iamc), and command parameters 
in text. 

Uppercase text indicates a command, the name of a routine, 
the name of a file, or the abbreviation for a system privilege. 

A hyphen in code examples indicates that additional 
arguments to the request are provided on the line that follows. 

All numbers in text are assumed to be decimal, unless 
otherwise noted. Nondecimal radixes—binary, octal, or 
hexadecimal—are explicitly indicated. 
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_1 

Overview of the LIB$ Facility 


1.1 Run-Time Library LIB$ Routines 

This manual discusses the Run-Time Library (RTL) LIB$ routines that perform 
general purpose (library) functions. One of the functions of the LIB$ facility is to 
provide a callable interface to components of OpenVMS operating systems that 
are difficult to use in a high-level language. LIB$ routines allow access to the 
following: 

• System services 

• The Command Language Interpreter (CLI) 

• Some VAX machine instructions or the equivalent AXP instructions 
In addition, LIB$ routines allow you to perform the following operations: 

• Allocate the resources that your process needs, such as virtual memory and 
event flags 

• Convert data types for I/O 

• Enable detection of hardware exceptions (OpenVMS VAX systems only) 

• Establish condition handlers (OpenVMS VAX systems only) 

• Generate and display timing statistics while your program is running 

• Get and put strings in the process common storage area 

• Obtain records from devices 

• Obtain the system date and time in various formats 

• Process cross-reference data 

• Search for specified files 

• Set up and use binary trees 

• Signal exceptions 

Table 1—1 contains all of the LIB$ routines and their functions. 
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Overview of the LIB$ Facility 

1.1 Run-Time Library LIB$ Routines 


Table 1-1 LIB$ Routines 

Routine Name Function 


LIB$ADAWI 

LIB$ADD_TIMES 

LIB$ADDX 

LIB$ANALYZE_SDESC 

LIB$ASN_WTH_MBX 

LIB$AST_IN_PROG 

LIB $ ATTACH 

LIB$BBCCI 

LIB$BBSSI 

LIB$CALLG 

LIB$CHAR 

LIB$CONVERT_DATE_STRING 

LIB$CRC 

LIB$CRC_TABLE 

LIB$CREATE_DIR 

LIB$CREATE_USER_VM_ZONE 

LIB$CREATE_VM_ZONE 

LIB$CRF_INS_KEY 

LIB$CRF_INS_REF 

LIB$CRF_OUTPUT 

LIB$CURRENCY 

LIB$CVT_DX_DX 

LIB$CVT_FROM_INTERNAL_TIME 

LIB$CVTF_FROM_INTERNAL_TIME 

LIB$CVT_TO_INTERNAL_TIME 

LIB$CVTF_TO_INTERNAL_TIME 

LIB$CVT_xTB 

LIB$CVT_VECTIM 

LIB$DATE_TIME 

LIB$DAY 

LIB$DAY_OF_WEEK 

LIB$DECODE_FAULT 

LIB$DEC_OVER 

LIB$DELETE_FILE 

LIB$DELETE_LOGICAL 

LIB$DELETE_SYMBOL 

LIB$DELETE_VM_ZONE 


Add adjacent word with interlock 

Add two quadwords times 

Add two multiple-precision binary numbers 

Analyze a string descriptor 

Assign a channel to a mailbox 

AST in progress 

Attach a terminal to a process 

Test and clear a bit with interlock 

Test and set a bit with interlock 

Call a procedure with a general argument list 

Transform a byte to the first character of a string 

Convert a date string to a quadword 

Calculate a Cyclic Redundancy Check (CRC) 

Construct a Cyclic Redundancy Check (CRC) table 

Create a directory 

Create a user-defined storage zone 

Create a new storage zone 

Insert a key in the cross-reference table 

Insert a reference to a key in the cross-reference table 

Output some cross-reference table information 

Get the system currency symbol 

Convert the specified data type 

Convert internal time to external time 

Convert internal time to external time (F-floating value) 

Convert external time to internal time 

Convert external time to internal time (F-floating value) 

Convert numeric text to binary 

Convert 7-word vector to internal time 

Return the date and time as a string 

Return the day number as a longword integer 

Return the numeric day of the week 

Decode instruction stream during a fault 1 

Enable or disable decimal overflow detection 1 

Delete one or more files 

Delete a logical name 

Delete a CLI symbol 

Delete a virtual memory zone 


1 Available only on OpenVMS VAX systems and for translated VAX applications running on OpenVMS AXP systems. 
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Table 1-1 (Cont.) LIB$ Routines 


Routine Name 

Function 

LIB$DIGIT_SEP 

Get the digit separator symbol 

LIB$DISABLE_CTRL 

Disable CLI interception of control characters 

LIB$DO_COMMAND 

Execute the specified command 

LIB$EDIV 

Perform an extended-precision divide 

LIB$EMODF 

Perform extended multiply and integerize for F-floating 
values 

LIB$EMODD 

Perform extended multiply and integerize for D-floating 
values 

LIB$EMODG 

Perform extended multiply and integerize for G-floating 
values 

LIB$EMODH 

Perform extended multiply and integerize for H-floating 
values 1 

LIB$EMUL 

Perform an extended-precision multiply 

LIB$ENABLE_CTRL 

Enable CLI interception of control characters 

LIB$ESTABLISH 

Establish a condition handler 1 2 

LIB$EXTV 

Extract a field and sign-extend 

LIB$EXTZV 

Extract a zero-extended field 

LIB$FFx 

Find the first clear or set bit 

LIB$FID_TO_NAME 

Convert a device and file ID to a file specification 

LIB$FILE_SCAN 

Perform a file scan 

LIB$FILE_SCAN_END 

End of file scan 

LIB$FIND_FILE 

Find a file 

LIB$FIND_FILE_END 

End of find file 

LIB$FIND_IMAGE_SYMBOL 

Merge activate an image symbol 

LIB$FIND_VM_ZONE 

Find the next valid zone 

LIB$FIXUP_FLT 

Fix floating reserved operand 1 

LIB$FLT_UNDER 

Floating-point underflow detection 1 

LIB$FORMAT_DATE_TIME 

Format a date and/or time 

tLIB$FORMAT_SOGW_PROT 

Format Protection Mask 

LIB$FREE_DATE_TIME_CONTEXT 

Free the context used to format a date 

LIB$FREE_EF 

Free an event flag 

LIB$FREE_LUN 

Free a logical unit number 

LIB$FREE_TIMER 

Free timer storage 

LIB$FREE_VM 

Free virtual memory from the program region 

LIB$FREE_VM_PAGE 

Free a virtual memory page 

LIB$GETDVI 

Get device/volume information 

LIB$GETJPI 

Get job/process information 

LIB$GETQUI 

Get queue information 


1 Available only on OpenVMS VAX systems and for translated VAX applications running on OpenVMS AXP systems. 
2 This routine or an equivalent mechanism is supplied by compilers on OpenVMS AXP systems. 
tOpenVMS VAX specific. 
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Table 1-1 (Cont.) LIBS Routines 

Routine Name Function 

LIB$GETSYI Get systemwide information 

fLIB$GET_ACCNAM Get Access Name Table for a Security Object Identified by 

Name 


tLIB$GET_ACCNAM_BY_CONTEXT 

LIB$GET_COMMAND 

LIB$GET_COMMON 

LIB$GET_CURR_INVO_CONTEXT 

LIB$GET_DATE_FORMAT 

LIB$GET_EF 

LIB$GET_FOREIGN 

LIB$GET_INPUT 

LIB$GET_INVO_CONTEXT 

LIB$GET_INVO_HANDLE 

LIB$GET_LUN 

LIB $GET_PRE V_INV 0_C ONTEXT 

LIB$GET_PREV_INVO_HANDLE 

LIB$GET_MAXIMUM_DATE_LENGTH 

LIB$GET_SYMBOL 

LIB$GET_U SERS_LAN GUAGE 

LIB$GET_VM 

LIB$GET_VM_PAGE 

LIB$ICHAR 

LIB$INDEX 

LIB$INIT_DATE_TIME_CONTEXT 

LIB$INIT_TIMER 

LIB$IN SERT_TREE 

LIB$INSQHI 

LIB$INSQTI 

LIB$INSV 

LIB$INT_OVER 

LIB$LEN 

LIB$LOCC 

LIB$LOOKUP_KEY 

LIB$LOOKUP_TREE 

LIB$LP_LINES 

LIB$MATCHC 

LIB$MATCH_COND 


Get Access Name Table for a Security Object Identified by 
$xET_SECURITY Context 

Get line from SYS$COMMAND 

Get string from common area 

Get Current Invocation Context 

Return the user’s date input format 

Get an event flag 

Get foreign command line 

Get line from SYS$INPUT 

Get Invocation Context 

Get Invocation Handle 

Get logical unit number 

Get Previous Invocation Context 

Get Previous Invocation Handle 

Get the maximum possible date/time string length 

Get the value of a CLI symbol 

Return the user’s language choice 

Allocate virtual memory 

Get a virtual memory page 

Convert first character of string to integer 

Index to relative position of substring 

Initialize the context used in formatting date/time strings 

Initialize times and counts 

Insert entry in a balanced binary tree 

Insert entry at the head of a queue 

Insert entry at the tail of a queue 

Insert a variable bit field 

Integer overflow detection 1 

Return the length of a string as a longword 

Locate a character 

Look up keyword in table 

Look up an entry in a balanced binary tree 

Specify the number of lines on each printer page 

Match characters, return relative position 

Match condition values 


1 Available only on OpenVMS VAX systems and for translated VAX applications running on OpenVMS AXP systems. 
tOpenVMS VAX specific. 
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Table 1-1 (Cont.) LIB$ Routines 


Routine Name 

Function 

LIB$MOVC3 

Move characters 

LIB$MOVC5 

Move characters with fill 

LIB$MOVTC 

Move translated characters 

LIB$MOVTUC 

Move translated until character 

LIB$MULT_DELTA_TIME 

Multiply delta time by scalar 

LIB$MULTF_DELTA_TIME 

Multiply delta time by F-floating scalar 

tLIB$PARSE_ACCESS_CODE 

Parse Access Encoded Name String 

tLIB$PARSE_SOGW_PROT 

Parse Protection String 

LIB$PAUSE 

Pause program execution 

LIB$POLYF 

Evaluate polynomials for F-floating values 

LIB$POLYD 

Evaluate polynomials for D-floating values 

LIB$POLYG 

Evaluate polynomials for G-floating values 

LIB$POLYH 

Evaluate polynomials for H-floating values 1 

LIB$PUT_COMMON 

Put string into common area 

LIB$PUT_INVO_REGISTERS 

Put Invocation Registers 

LIB$PUT_OUTPUT 

Put line to SYS$OUTPUT 

LIB$RADIX_POINT 

Radix point symbol 

LIB$REMQHI 

Remove entry from head of queue 

LIB$REMQTI 

Remove entry from tail of queue 

LIB$RENAME_FILE 

Rename one or more files 

LIB$RESERVE_EF 

Reserve an event flag 

LIB$RESET_VM_ZONE 

Reset virtual memory zone 

LIB$REVERT 

Revert to the handler of the procedure activator 1 , 2 

LIB$RUN_PROGRAM 

Run new program 

LIB$SCANC 

Scan for characters and return relative position 

LIB$SCOPY_DXDX 

Copy source string by descriptor to destination 

LIB$SCOPY_R_DX 

Copy source string by reference to destination 

LIB$SET_LOGICAL 

Set logical name 

LIB$SET_SYMBOL 

Set value of a CLI symbol 

LIB$SFREE 1_DD 

Free one or more dynamic strings 

LIB$SFREEN_DD 

Free n dynamic strings 

LIB$SGET1_DD 

Get one dynamic string 

LIB$SHOW_TIMER 

Show accumulated times and counts 

LIB$SHOW_VM 

Show virtual memory statistics 

LIB$SHOW_VM_ZONE 

Display information about a virtual memory zone 

LIB$SIGNAL 

Signal exception condition 


1 Available only on OpenVMS VAX systems and for translated VAX applications running on OpenVMS AXP systems. 
2 This routine or an equivalent mechanism is supplied by compilers on OpenVMS AXP systems. 
tOpenVMS VAX specific. 
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1.1 Run-Time Library LIB$ Routines 


Table 1-1 (Cont.) LIB$ Routines 

Routine Name Function 


LIB$SIG_TO_RET 

LIB$SIG_TO_STOP 

LIB$SIM_TRAP 

LIB$SKPC 

LIB$SPANC 

LIB $ SPAWN 

LIB$STAT_TIMER 

LIB$STAT_VM 

LIB$STOP 

LIB$SUB_TIMES 

LIB$SUBX 

LIB$SYS_ASCTIM 

LIB$SYS_FAO 

LIB$SYS_FAOL 

LIB$SYS_GETMSG 

LIB$TPARSE 

$LIB$TABLE_PARSE 

LIB$TRA_ASC_EBC 

LIB$TRA_EBC_ASC 

LIB$TRAVERSE_TREE 

LIB$TRIM_FILESPEC 

LIB$VERIFY_VM_ZONE 

LIB $ WAIT 


Convert signaled message to a return status 

Convert a signaled condition to a signaled stop 

Simulate floating trap 1 

Skip equal characters 

Skip selected characters 

Spawn a subprocess 

Return accumulated time and count statistics 

Return virtual memory statistics 

Stop execution and signal the condition 

Subtract two quadword times 

Perform multiple-precision binary subtraction 

Invoke $ASCTIM to convert binary time to ASCII 

Invoke $FAO system service to format output 

Invoke $FAOL system service to format output 

Invoke $GETMSG system service to get message text 

Implement a table-driven, finite-state parser 1 

Implement a table-driven, finite-state parser 

Translate ASCII to EBCDIC 

Translate EBCDIC to ASCII 

Traverse a balanced binary tree 

Fit long file specification into fixed field 

Verify a virtual memory zone 

Wait a specified period of time 


Available only on OpenVMS VAX systems and for translated VAX applications running on OpenVMS AXP systems. 
^OpenVMS AXP specific. 


1.2 Translated Version of LIB$ Facility (OpenVMS AXP Only) 

The RTL LIB$ facility exists in two forms on OpenVMS AXP systems: native and 
translated. The translated LIB$ library contains routines specific to VAX systems 
only, and are executed in the Translated Image Environment (TIE). These 
routines are not available to native OpenVMS AXP programs. See DECmigrate 
for OpenVMS AXP Version 1.0 Translating Images for additional information on 
using translated images and the TIE. 

Table 1—2 lists the translated LIB$ routines. 
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Overview of the LIB$ Facility 
1.2 Translated Version of LIB$ Facility (OpenVMS AXP Only) 


Table 1-2 Translated LIB$ Routines 


Routine Name 

Restriction 

LIB$DECODE_FAULT 

Decodes VAX instructions 

LIB$DEC_OVER 

Applies to VAX PSL only 

LIB$ESTABLISH 

Supported by compilers on OpenVMS AXP systems 

LIB$FIXUP_FLT 

Applies to VAX PSL only 

LIB$FLT_UNDER 

Applies to VAX PSL only 

LIB$INT_OVER 

Applies to VAX PSL only 

LIB$REVERT 

Supported by compilers on OpenVMS AXP systems 

LIB$SIM_TRAP 

Applies to VAX code 

LIB$TPARSE 

Requires action routine interface changes. Replaced by 
LIB$TABLE_PARSE 


LIB$ routines that are called using JSB linkages may function differently on 
OpenVMS VAX and OpenVMS AXP systems. See OpenVMS Programming 
Interfaces: Calling a System Routine for more information on using JSB linkages. 

1.3 Run-Time Library CVT$ Facility (OpenVMS AXP Only) 

This manual describes the Run-Time Library CVT$ facility and its 
CVT$CONVERT_FLOAT routine. The CVT$ facility lets you convert data 
stored in one OpenVMS data type into data for another data type. For example: 
CVT$CONVERT_FLOAT converts data in one of several floating point data types 
to another floating point data type. ♦ 


AXP 
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LIB$ Reference Section 


This section contains detailed discussions of the routines provided by the 
OpenVMS RTL Library (LIB$) Facility. 






LIBSADAWI 


LIBSADAWI—Add Aligned Word with Interlock 

The Add Aligned Word with Interlock routine allows the user to perform an 
interlocked add operation using an aligned word. 


Format 

LIBSADAWI add ,sum .sign 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Arguments 


add 

OpenVMS usage 

type 

access 

mechanism 


word_signed 
word (signed) 
read only 
by reference 


The addend operand to be added to the value of sum. The add argument is the 
address of a signed word that contains the addend operand. 


sum 

OpenVMS usage word_signed 
type word integer (signed) 

access modify 

mechanism by reference 

The word to which add is added. The sum argument is the address of a signed 
word integer containing this value. The add operand is added to the sum 
operand, and the value of the sum argument is replaced by the result of this 
addition. The sum argument must be word-aligned, in other words, its address 
must be a multiple of 2. 

sign 

OpenVMS usage word_signed 
type word integer (signed) 

access write only 

mechanism by reference 

Sign of the sum argument. The sign argument is the address of a signed word 
integer that is assigned the value —1, 0, or 1, depending on whether the new 
value of sum is negative, 0, or positive. 


✓ 
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LIBSADAWI 


Description 

LIB$ADAWI allows the user to perform an interlocked add operation using an 
aligned word, and makes the VAX ADAWI 1 instruction available as a callable 
routine. This routine also enables the user to implement synchronization 
primitives for multiprocessing. 

The add operation is interlocked against similar operations on other processors in 
a multiprocessor environment. This provides an atomic addition operation. The 
destination must be aligned on a word boundary; that is, bit 0 of the address of 
the sum operand must be 0. 

If the addend and the sum operand overlap, the result of the addition, the value 
of the sign argument, and the associated condition codes are unpredictable. 

The value of the sign argument is useful when LIB$ADAWI is used to implement 
locking in a multiprocessing program. For example, a process that is waiting to 
seize a lock or a resource calls LIB$ADAWI to add 1 to the sum. When the call 
returns, the waiting process checks the value of sign. 

One possible algorithm would interpret the value of sign as follows: 


Value of sign Status of lock or resource 

-1 Open lock or free resources 

0 Closed lock or no free resources, with no processes waiting 

+1 Closed lock or no free resources, with processes waiting 


In this algorithm, if the value of the sign argument is -1, that indicates that 
the process successfully seized the lock or resource, and other free resources are 
available. A value of 0 indicates that the process successfully seized the lock or 
the last available resource. A value of 1 indicates that the process was unable to 
seize the lock. 

It is not sufficient for a waiting process to test the value of sum. The result 
is unpredictable because other processes can alter the value of sum after the 
original process executes the ADAWI instruction but before it tests the value 
of sum. However, a process can safely test the value of sign because its value 
is determined by the ADAWI instruction and is unaffected by other processes’ 
activities. 

Condition Values Returned 

SS$_NORMAL Routine successfully completed. 

LIB$_INTOVF Integer overflow error. 


1 On AXP systems, OpenVMS AXP instructions perform the equivalent operation. 
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LIB$ADD_TIMES 


LIB$ADD_TIMES—Add Two Quadword Times 

The Add Two Quadword Times routine adds two internal format times. 


Format 

LIB$ADD_TIMES timel ,time2 ,resultant-time 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Arguments 


timel 

OpenVMS usage 

type 

access 

mechanism 


date_time 

quadword (unsigned) 
read only 
by reference 


First time that LIB$ADD_TIMES adds to the second time. The timel argument 
is the address of an unsigned quadword containing the first time to be added. 
Timel may be either a delta time or an absolute time; however, at least one of 
the arguments, timel or time2, must be a delta time. 


time2 

OpenVMS usage date_time 
type quadword (unsigned) 

access read only 

mechanism by reference 

Second time that LIB$ADD_TIMES adds to the first time. The time2 argument 
is the address of an unsigned quadword containing the second time to be added. 
Time2 may be either a delta time or an absolute time; however, at least one of 
the arguments, timel or time2, must be a delta time. 


resultant-time 

OpenVMS usage date_time 
type quadword (unsigned) 

access write only 

mechanism by reference 

The result of adding timel and time2. The resultant-time argument is the 
address of an unsigned quadword containing the result. If both timel and time2 
are delta times, then resultant-time is a delta time. Otherwise, resultant-time 
is an absolute time. 


Description 

LIB$ADD_TIMES adds two OpenVMS internal times. It can add two delta times 
or a delta time and an absolute time. LIB$ADD_TIMES cannot add two absolute 
times. Delta times must be less than 10,000 days. 
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Condition Values Returned 

LIB$_NORMAL Routine successfully completed. 

LIB$_IVTIME Invalid time. 

LIB$_ONEDELTIM At least one delta time is required. 

LIB$_WRONUMARG Incorrect number of arguments. 
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LIBSADDX 


LIBSADDX—Add Two Multiple-Precision Binary Numbers 

The Add Two Multiple-Precision Binary Numbers routine adds two signed two’s 
complement integers of arbitrary length. 

Format 

UB$ADDX addend-array ,augend-array ,resultant-array [,array-length] 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Arguments 

addend-array 

OpenVMS usage vector_longword_signed 
type unspecified 

access read only 

mechanism by reference, array reference 

First multiple-precision, signed two’s complement integer which LIB$ADDX adds 
to the second two’s complement integer. The addend-array argument is the 
address of the array containing the two’s complement number to be added. 

augend-array 

OpenVMS usage vector_longword_signed 
type unspecified 

access read only 

mechanism by reference, array reference 

Second multiple-precision, signed two’s complement integer, which LIB$ADDX 
adds to the first two’s complement integer. The augend-array argument is the 
address of the array containing the two’s complement number. 

resultant-array 

OpenVMS usage vector_longword_signed 
type unspecified 

access write only 

mechanism by reference, array reference 

Multiple-precision, signed two’s complement integer result of the addition. The 
resultant-array argument is the address of the array into which LIB$ADDX 
writes the result of the addition. 

array-length 

OpenVMS usage longword_signed 
type longword integer (signed) 

access read only 

mechanism by reference 

Length in longwords of the arrays to be operated on; each array is of length len. 
The len argument is the address of a signed longword integer containing the 


cond_value 
longword (unsigned) 
write only 
by value 
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length. Len must not be negative. This is an optional argument. If omitted, the 
default is 2. 


Description 

LIB$ADDX adds two signed two’s complement integers of arbitrary length. 

The integers are located in arrays of longwords. The higher addresses of 
these longwords contain the higher-precision parts of the values. The highest- 
addressed longword contains the sign and 31 bits of precision. The remaining 
longwords contain 32 bits of precision in each. The number of longwords in each 
array is specified in the optional argument, len. The default length is two, which 
corresponds to the OpenVMS quadword data type. 

Any two or all three of the first three arguments can be the same. 

Condition Values Returned 

SS$_NORMAL Routine successfully completed. 

SS$_INTOVF Integer overflow. The result is correct, except 

that the sign bit is lost. 


Example 


c+ 

C This FORTRAN example program shows the use 
C of LIB$ADDX. 

C- 


INTEGER A(2),B(2),C(2),RETURN 
DATA A/'OOOOOOOl'x,'7FFF407F'x/ 
DATA B/'FFFFFFFF'x,'8000BF80'x/ 


C+ 

C The highest addressed longword of "A" is A(2). 

C So, "A" represents the integer value ('7FFF407F'x) * 16**7 + 1. 
C That is, A(2) is 576447592255193089. 

C "B" is the twos complement representation of "-A". 

C- 

RETURN = LIB$ADDX(A,B,C) 

TYPE *,'Let A = 576447592255193089.' 

TYPE *,'Then A + B is 0.' 

TYPE 1,C(2),C(1) 

1 FORMAT(' "A" - "A" is ',1H',II,II,3H'x.) 

TYPE *,'Note that C is C(2) concatenated with C(l).' 

C+ 

C Let "A" have the value 72057594037927937 = '1000000000000001'x. 
C Let "B" have the value 4294967295 = 'OOOOOOOOFFFFFFFF'x. 

C- 


C+ 

C Then 
C- 


A(1) = '00000001'x 
A(2) = '10000000'x 
B(1) = 'FFFFFFFF'x 
B(2) = '00000000'x 

"A" + "B" is 72057598332895232. 
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RETURN = LIB$ADDX(A,B,C) 

TYPE *, ' ' 

TYPE *,'LET A = 72057594037927937 and B = 4294967295' 

TYPE *,'Then A + B is ',C 
TYPE 2,C(2),C(1) 

2 FORMAT(' 72057598332895232 is represented as ',1H',Z8.8,Z8.8,3H'x.) 

TYPE *,'Recall that 72057598332895232 is C(2) concatenated 
1 with C(1).' 

END 

This FORTRAN example demonstrates how to call LIB$ADDX. The output 
generated by this program is as follows: 

Let A = 576447592255193089. 

Then A + B is 0. 

"A" - "A" is '00'x. 

Note that C is C(2) concatenated with C(l). 

LET A = 72057594037927937 and B = 4294967295 
Then A + B is 0 268435457 

72057598332895232 is represented as '10000001 0'x. 

Recall that 72057598332895232 is C(2) concatenated with C(l). 



LIB$ANALYZE_SDESC 


LIB$ANALYZE_SDESC—Analyze String Descriptors 

The Analyze String Descriptors routine extracts the length and the address at 
which the data starts for a variety of string descriptor classes. 


Format 


LIB$ANALYZE_SDESC input-descriptor ,data-length ,data-address 


Corresponding JSB Entry Point: 

LIB$ANALYZE_SDESC_R2 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Arguments 


input-descriptor 

OpenVMS usage 

type 

access 

mechanism 


descriptor 

quadword (unsigned) 
read only 
by reference 


Input descriptor from which LIB$ANALYZE_SDESC extracts the data’s length 
and starting address. The input-descriptor argument is the address of a 
descriptor pointing to this descriptor. 


data-length 

OpenVMS usage word_unsigned 
type word (unsigned) 

access write only 

mechanism by reference 

Length of the data; LIB$ANALYSE_SDESC extracts this length value from the 
input descriptor. The data-length argument is the address of an unsigned word 
integer into which LIB$ANALYZE_SDESC writes the length. 

data-address 

OpenVMS usage address 
type longword (unsigned) 

access write only 

mechanism by reference 

Starting address of the data; LIB$ANALYZE_SDESC extracts this address from 
the input descriptor. The data-address argument is the address of an unsigned 
longword into which LIB$ANALYZE_SDESC writes the starting address of the 
data. 
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Description 


LIB$ANALYZE_SDESC extracts the length and the address at which the data 
starts for a variety of string descriptor classes. Following is a description of the 
classes of string descriptors. 


Class 

Description 

Restrictions/Notes 

A 

Array 

DSC$L_ARSIZE must be less than 
65536 bytes. 

D 

Decimal string 

Treated as Class S. 

NCA 

Noncontiguous array 

Same as Class A. 

S 

Scalar, string 

None. 

SD 

Decimal scalar 

Treated as Class S. 

VS 

Varying string 

Length returned is CURLEN. 

z 

Unspecified 

Treated as Class S. 


See STR$ANALYZE_SDESC for a similar routine that signals an error rather 
than returning a status. 


Condition Values Returned 

SS$_NORMAL Routine successfully completed. 

LIB$_INVSTRDES Invalid string descriptor. An array descriptor 

has an ARSIZE greater than 65,535 bytes, or the 
class is unsupported. 
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LIB$ASN_WTH_MBX—Assign Channel with Mailbox 

The Assign Channel with Mailbox routine assigns a channel to a specified device 
and associates a mailbox with the device. It returns both the device channel and 
the mailbox channel. 

Format 

UB$ASN_WTH_MBX device-name [,maximum-message-size] [,buffer-quota] ,device-channel 
,mailbox-channel 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Arguments 

device-name 

OpenVMS usage device_name 
type character string 

access read only 

mechanism by descriptor 

Device name that LIB$ASN_WTH_MBX passes to the $ASSIGN service. The 
device-name argument is the address of a descriptor pointing to the device 
name. 

maximum-message-size 

OpenVMS usage longword_signed 
type longword integer (signed) 

access read only 

mechanism by reference 

Maximum message size that can be sent to the mailbox; LIB$ASN_WTH_MBX 
passes this argument to the $CREMBX service. The maximum-message-size 
argument is the address of a signed longword integer containing this maximum 
message size. 

buffer-quota 

OpenVMS usage longword_signed 
type longword integer (signed) 

access read only 

mechanism by reference 

Number of system dynamic memory bytes that can be used to buffer messages 
sent to the mailbox; LIB$ASN_WTH_MBX passes this argument to the 
$CREMBX service. The buffer-quota argument is the address of a signed 
longword integer containing this buffer quota. 


cond_value 
longword (unsigned) 
write only 
by value 
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LIB$ASN_WTH_MBX 


device-channel 

OpenVMS usage word_unsigned 
type word integer (unsigned) 

access write only 

mechanism by reference 

Device channel that LIB$ASN_WTH_MBX receives from the $ASSIGN service. 
The device-channel argument is the address of an unsigned word integer into 
which $ASSIGN writes the device channel. 

mailbox-channel 

OpenVMS usage channel 
type word integer (unsigned) 

access write only 

mechanism by reference 

Mailbox channel that LIB$ASN_WTH_MBX receives from the $CREMBX service. 
The mailbox-channel argument is the address of an unsigned word integer into 
which $CREMBX writes the mailbox channel. 


Description 

A mailbox is a virtual device used for communication between processes. A 
channel is the communication path that a process uses to perform I/O operations 
to a particular device. LIB$ASN_WTH_MBX assigns a channel to a device and 
associates a mailbox with the device. It returns both the device channel and the 
mailbox channel to the mailbox. 

Normally, a process calls the $CREMBX system service to create a mailbox and 
assign a channel and logical name to it. Any process running in the same job and 
using the same logical name uses the same mailbox. 

LIB$ASN_WTH_MBX associates the physical mailbox name with the channel 
assigned to the device. To create a temporary mailbox for itself and other 
processes cooperating with it, your program calls LIB$ASN_WTH_MBX. The 
Run-Time Library routine assigns the channel and creates the temporary mailbox 
by using the system services $GETDVIW, $ASSIGN, and $CREMBX. Instead of 
a logical name, the mailbox is identified by a physical device name of the form 
MBcu. The physical device name MBcu is made up of the following elements: 

MB Indicates that the device is a mailbox 
c Is the controller 

u Is the unit number 

The routine returns the channel for this device name to the calling program, 
which then must pass the mailbox channel to the other program(s) with which 
it cooperates. In this way, the cooperating processes access the mailbox by its 
physical name, instead of by a logical name. 

The calling program passes the routine a device name, which specifies the device 
to which the channel is to be assigned. For this argument (called device-name), 
you may use a logical name. If you do so, the routine attempts one level of logical 
name translation. 

The privilege restrictions and process quotas required for using this routine are 
those required by the $GETDVIW, $CREMBX, and $ASSIGN system services. 
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Condition Values Returned 

SS$_NORMAL Routine successfully completed. 

Any condition value returned by the called system services $ASSIGN, $CREMBX, 
$GETDVI, or the RTL routines LIB$GET_EF and LIB$FREE_EF. 
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LIB$AST_lN_PROG—AST in Progress 

The AST in Progress routine indicates whether an AST is currently in progress. 


Format 

UB$AST_IN_PROG 

Returns 

OpenVMS usage boolean 
type boolean 

access write only 

mechanism by value 

Truth value that indicates whether an AST is currently in progress (value=l) or 
not (value=0). 

Arguments 

None. 

Description 

An asynchronous system trap (AST) is an OpenVMS mechanism for providing a 
software interrupt when an external event occurs, such as the user typing Ctrl/c. 
When an external event occurs, the OpenVMS operating system interrupts the 
execution of the current process and calls a routine that you supply. While that 
routine is active, the AST is said to be in progress, and the process is said to be 
executing at AST level. When your AST routine returns control to the original 
process, the AST is no longer active and execution continues where it left off. 

LIB$AST_IN_PROG indicates to the calling program whether an AST is currently 
in progress. Your program can call LIB$AST_IN_PROG to determine whether it 
is executing at AST level, and then take appropriate action. This routine is useful 
if you are writing AST-reentrant code, which takes different actions depending 
on whether an AST is in progress. For example, the routine might have two 
separate statically allocated storage areas, one for AST level and one for non-AST 
level. 

Condition Values Returned 

Any condition values returned by LIB$FREE_EF, LIB$GET_EF, or SYS$GETJPI. 
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Example 


PROGRAM AST_IN_PROGRESS(INPUT, OUTPUT); 

FUNCTION LIB$AST_IN_PROG : INTEGER; EXTERN; 

VAR 

ASTVALUE : INTEGER; 

BEGIN 

ASTVALUE := LIB$AST_IN_PROG; 

CASE ASTVALUE OF 

0 : WRITELN( 'AN AST IS NOT IN PROGRESS'); 

1 : WRITELN('AN AST IS IN PROGRESS'); 

END { of the case statement } 

END. 

This Pascal program determines whether or not an AST is in progress. 
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LIB$ATTACH—Attach Terminal to Process 

The Attach Terminal to Process routine requests the calling process’s Command 
Language Interpreter (CLI) to detach the terminal of the calling process and to 
reattach it to a different process. 


Format 

LIB$ATTACH process-id 


Returns 


Argument 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


process-id 

OpenVMS usage 

type 

access 

mechanism 


processed 

longword integer (unsigned) 
read only 
by reference 


Identification of the process to which LIB$ATTACH requests the calling process 
to attach its terminal. The process-id argument is the address of an unsigned 
longword integer containing the process identification. The specified process must 
be currently detached (by means of a SPAWN or ATTACH command, or by a call 
to LIB$SPAWN or LIB$ATTACH) and must be part of the caller’s job. 


Description 

LIB$ATTACH requests the calling process’s Command Language Interpreter 
(CLI) to detach the terminal of the calling process and reattach it to a different 
process. The calling process then hibernates. LIB$ATTACH provides the same 
function as the DCL command ATTACH. For more information, see the OpenVMS 
DCL Dictionary. 

LIB$ATTACH is supported for use with the DCL CLI. If used with the Monitor 
Control Routine (MCR) CLI, the error status LIB$_NOCLI will be returned. If 
an image is run directly as a subprocess or detached process, no CLI is present to 
perform this function. In such cases the error status LIB$_NOCLI is returned. 


Condition Values Returned 

SS$_N ORMAL 
SS$_N ONEXPR 

LIB$_ATTREQREF 


Routine successfully completed. 

Nonexistent process. The process specified by 
process-id does not exist. 

Attach request refused. The specified process 
could not be attached to. Either it was not 
detached, or did not belong to the caller’s job. 
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LIB$_NOCLI No CLI present to perform function. The calling 

process did not have a CLI to perform the 
function, or the CLI did not support the request 
type. Note that an image run as a subprocess or 
detached process does not have a CLI. 

LIB$_UNECLIERR Unexpected CLI error. The CLI returned an 

error status, which was not recognized. This 
error may be caused by use of a nonstandard 
CLI. If this error occurs while using the DCL 
CLI, please report the problem to Digital by 
means of a Software Performance Report (SPR). 
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LIBSBBCCI—Test and Clear Bit with Interlock 

The Test and Clear Bit with Interlock routine tests and clears a selected bit under 
memory interlock. LIB$BBCCI makes the VAX BBCCI 1 instruction available as 
a callable routine. 


Format 

LIBSBBCCI position ,bit-zero-address 


Returns 


OpenVMS usage longword_unsigned 
type longword (unsigned) 

access write only 

mechanism by value 

State of the bit before it was cleared by LIB$BBCCI: 1 if the bit was previously 
set, and 0 if the bit was previously clear. 


Arguments 

position 

OpenVMS usage longword_signed 
type longword integer (signed) 

access read only 

mechanism by reference 

Bit position, relative to bit-zero-address of the bit that LIB$BBCCI tests and 
clears. The position argument is the address of a signed longword integer 
containing the bit position. A position of zero denotes the low-order bit of the 
byte base. The bit position is equal to the offset of the bit chosen from the base 
position. This offset may span the entire range of a signed longword integer; 
negative offsets access bits in lower-addressed bytes. 

bit-zero-address 

OpenVMS usage unspecified 
type address 

access modify 

mechanism by reference 

Address of the byte containing bit zero of the field that LIB$BBCCI references. 
The bit-zero-address argument is the location of the base position. The bit 
that LIB$BBCCI tests and clears is position bits offset from the low bit of 

bit-zero-address. 


Description 

The single bit specified by position and bit-zero-address is tested, the previous 
state of the bit remembered, and the bit cleared. The reading of the state of the 
bit and its clearing are interlocked against similar operations by other processors 
or devices in the system. The remembered previous state of the bit is then 
returned as the function value of LIB$BBCCI. 


1 On AXP systems, OpenVMS AXP instructions perform the equivalent operation. 
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Condition Values Returned 

None. 


Example 


c+ 

C This FORTRAN program demonstrates the use of 
C LIB$BBCCI. 

C- 


INTEGER*4 STATES(4) ! 128 shared state bits 

COMMON /STATES/ STATES ! Could be shared memory 
L0GICAL*4 LIB$BBCCI 

IF (LIB$BBCCI (42, STATES)) THEN 
TYPE State bit 42 was set' 

ELSE 

TYPE State bit 42 was clear' 

END IF 
END 

This FORTRAN example tests and clears bit 42 of array STATES, which is in a 
COMMON area (possibly shared between two processors). 

The output generated by this program is as follows: 

$ RUN STATE 

State bit 42 was clear. 
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LIBSBBSSI—Test and Set Bit with Interlock 

The Test and Set Bit with Interlock routine tests and sets a selected bit under 
memory interlock. LIB$BBSSI makes the VAX BBSSI 1 instruction available as a 
callable routine. 


Format 

LIBSBBSSI position ,bit-zero-address 

Returns 


OpenVMS usage longword_unsigned 
type longword (unsigned) 

access write only 

mechanism by value 

The state of the bit before it was set by LIB$BBSSI: 1 if it was previously set, 
and 0 if it was previously clear. 


Arguments 

position 

OpenVMS usage longword_signed 
type longword integer (signed) 

access read only 

mechanism by reference 

Bit position, relative to bit-zero-address of the bit that LIB$BBSSI tests 
and sets. The position argument is the address of a signed longword integer 
containing the bit position. A position of zero denotes the low-order bit of the 
byte base. The bit position is equal to the offset of the bit chosen from the base 
position. This offset may span the entire range of a signed longword integer; 
negative offsets access bits in lower-addressed bytes. 

bit-zero-address 

OpenVMS usage unspecified 
type address 

access modify 

mechanism by reference 

Address of the byte containing bit zero of the field that LIB$BBSSI references. 
The bit-zero-address argument is the location of the base position. The bit that 
LIB$BBSSI tests and sets is position bits offset from the low bit of bit-zero- 
address. 


Description 

The single bit specified by position and bit-zero-address arguments is tested, 
the previous state of the bit remembered, and the bit set. The reading of the 
state of the bit and its setting are interlocked against similar operations by other 
processors or devices in the system. The remembered previous state of the bit is 
then returned as the function value of LIB$BBSSI. 


1 On AXP systems, OpenVMS AXP instructions perform the equivalent operation. 
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Condition Values Returned 

None. 


Example 


c+ 

C This FORTRAN example program demonstrates 
C the use of LIB$BBSSI. 

C- 

INTEGER*4 STATES(4) ! 128 shared state bits 

COMMON /STATES/ STATES ! Could be shared memory 
LOGICAL*4 LIB$BBSSI 

IF (LIB$BBSSI (104, STATES)) THEN 
TYPE * f 'State bit 104 was set' 

ELSE 

TYPE *,'State bit 104 was clear' 

END IF 
END 

This FORTRAN example tests and sets bit 104 of array STATES, which is in a 
COMMON storage area (possibly shared between two processors). 

The output generated by this program is as follows: 

$ RUN STATEB 

State bit 104 was clear. 
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LIBSCALLG—Call Routine with General Argument List 

The Call Routine with General Argument List routine calls a routine with an 
argument list specified as an array of longwords, the first of which is a count of 
the remaining longwords. LIB$CALLG is a callable version of the VAX CALLG 1 
instruction. 


Format 

LIBSCALLG argument-list ,user-procedure 

Returns 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access write only 

mechanism by value 

Return value, if any, of the called routine. This value is not changed by 
LIB$CALLG. 

Arguments 

argument-list 

OpenVMS usage arg_list 

type unspecified 

access read only 

mechanism by reference, array reference 

Argument list that LIB$CALLG uses to call the specified routine. The 
argument-list argument is the address of an array of longwords containing 
the argument list. The first longword must contain the count of the remaining 
longwords. The maximum value of the count is 255. 

user-procedure 

OpenVMS usage procedure 

type procedure value 

access function call (before return) 

mechanism by value 

Routine that LIB$CALLG calls with the specified argument list. 

Description 

LIB$CALLG is useful for calling routines that accept variable-length argument 
lists when the number of arguments to be passed is not known until execution 
time. LIB$CALLG can also be used to call such routines from strongly typed 
languages, which require routines to be declared as having a fixed number of 
arguments. 


1 On AXP systems, OpenVMS AXP instructions perform the equivalent operation. 
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Condition Values Returned 

None. 
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LIBSCHAR—Transform Byte to First Character of String 

The Transform Byte to First Character of String routine transforms a single 8-bit 
ASCII character to an ASCII string consisting of a single character followed by 
trailing spaces, if needed, to fill out the string. The range of the input byte is 0 
through 255. 


Format 

LIBSCHAR one-character-string ,ascii-code 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 


Arguments 

one-character-string 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor 

ASCII character string consisting of a single character followed by trailing spaces, 
if needed, that LIB$CHAR creates when it transforms the ASCII character code. 
The one-character-string argument is the address of a descriptor pointing to 
the character string that LIB$CHAR writes. 

ascii-code 

OpenVMS usage byte_unsigned 
type byte (unsigned) 

access read only 

mechanism by reference 

Single 8-bit ASCII character code that LIB$CHAR transforms to an ASCII string. 
The ascii-code argument is the address of an unsigned byte containing the 
ASCII character code. 


Description 

LIB$CHAR is the inverse of LIB$ICHAR. (See the description of LIB$ICHAR.) 
LIB$CHAR is not a binary-to-ASCII conversion routine. LIB$CHAR merely 
interprets ascii-code as an ASCII character code and converts it to a string. 

Condition Values Returned 

SS$_NORMAL Routine successfully completed. 

LIB$_STRTRU Routine successfully completed, but the string 

was truncated. The fixed-length destination 
string could not contain all of the characters. 
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LIB$_FATERRLIB 


LIB$_INSVIRMEM 

LIB$_INVSTRDES 


Fatal internal error. An internal consistency 
check has failed. This usually indicates an 
internal error in the Run-Time Library and 
should be reported to Digital in a Software 
Performance Report (SPR). 

Insufficient virtual memory. A call to LIB$GET_ 
VM has failed because your program has 
exceeded the image quota for virtual memory. 

Invalid string descriptor. A string descriptor has 
an invalid value in its DSC$B_CLASS field. 
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LIB$CONVERT_DATE_STRING—Convert Date String to Quadword 

The Convert Date String to Quadword routine converts an absolute date string 
into an OpenVMS internal format date-time quadword. That is, given an input 
date/time string of a specified format, LIB$CONVERT_DATE_STRING converts 
this string to an OpenVMS internal format time. 

Format 

LIB$CONVERT_DATE_STRING date-string ,date-time [,user-context] [.flags] [.defaults] [.defaulted-fields] 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Arguments 

date-string 

OpenVMS usage time_name 
type character-coded text string 

access read only 

mechanism by descriptor 

Date string that specifies the absolute time to be converted to an internal system 
time. The date-string argument is the address of a descriptor pointing to this 
date string. This string must have a format corresponding to the currently 
defined input format, or it must be one of the relative day strings YESTERDAY, 
TODAY, or TOMORROW, or their equivalents in the currently selected language. 

date-time 

OpenVMS usage date_time 
type quadword (unsigned) 

access write only 

mechanism by reference 

Receives the converted time. The date-time argument is the address of an 
unsigned quadword that contains this OpenVMS internal format converted time. 

user-context 

OpenVMS usage context 
type longword (unsigned) 

access modify 

mechanism by reference 

Context variable that retains the translation context over multiple calls to this 
routine. The user-context argument is the address of an unsigned longword 
that contains this context. The initial value of the context variable must be zero. 
Thereafter, the user program must not write to the cell. 

The user-context parameter is optional. However, if a context cell is not 
passed, the routine LIB$CONVERT_DATE_STRING may abort if two threads of 
execution attempt to manipulate the context area concurrently. Therefore, when 
calling this routine in situations where reentrancy might occur, such as from 


cond_value 
longword (unsigned) 
write only 
by value 
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AST level, Digital recommends that users specify a different context cell for each 
calling thread. 

flags 

OpenVMS usage maskjongword 
type longword (unsigned) 

access read only 

mechanism by reference 

Specifies which date or time fields of the date-string argument might be omitted 
so that default values are applied. The flags argument is the address of a 
longword bit mask that contains these flags. A set bit indicates that the field 
may be omitted. The bit definitions for the mask correspond to the fields in a 
$NUMTIM “timbuf” structure as follows: 


Field 

Bit Number 

Mask 

Year 

0 

1 

Month 

1 

2 

Day of month 

2 

4 

Hours 

3 

8 

Minutes 

4 

16 

Seconds 

5 

32 

Fractional seconds 

6 

64 


Bits 7 through 31 must be zero and are reserved for use by Digital. If this 
parameter is omitted, a default value of 120 (78H) is used, indicating that the 
time fields may be defaulted, but the date fields may not. 

defaults 

OpenVMS usage vector_word_unsigned 
type word (unsigned) 

access read only 

mechanism by reference, array reference 

Supplies the defaults to be used for omitted fields. The 
address of an array of unsigned words containing these 
corresponds to a 7-word $NUMTIM “timbuf’ structure, 
is omitted, the following defaults are applied: 

• For the date group, the default is the current date. 

• For the time group, the default is 00:00:00.00. 

defaulted-fields 

OpenVMS usage maskjongword 
type longword (unsigned) 

access write only 

mechanism by reference 

Indicates which date or time fields have been defaulted. The defaulted-fields 
argument is the address of a longword bit mask that specifies these fields. The 
bit definitions are identical to those of the flags bit mask. A set bit indicates that 
the field was defaulted. Bits 7 through 31, which are reserved for use by Digital, 
are zeroed. 


defaults argument is the 
default values. This array 
If the defaults argument 
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Description 

LIB$CONVERT_DATE_STRING converts an absolute date string into an 
OpenVMS internal format date-time quadword. The input date string can 
either correspond to the format specified, or it can be the language equivalent 
of one of the relative date strings YESTERDAY, TODAY, or TOMORROW. The 
language to be used and the format in which to interpret the information are 
programmable using either of the following methods. 

• The language and format are programmable at compile time through the use 
of the routine LIB$INIT_DATE_TIME_CONTEXT. 

• The language and format can be determined at run time through the 
translation of the logical names SYS$LANGUAGE and LIB$DT_INPUT_ 
FORMAT. 

In general, if an application is reading text from internal storage, the language 
and input format should be specified at compile time. If this is the case, use the 
routine LIB$INIT_DATE_TIME_CONTEXT to specify the language and input 
format of your choice. 

If an application is accepting text from a user, the logical name method of 
specifying language and format should be used. In this method, the user assigns 
equivalence names to the logical names SYS$LANGUAGE and LIB$DT_INPUT_ 
FORMAT, thereby selecting the language and input format of the date and time 
at run time. 

The calling program can choose to apply defaults for omitted fields in the date 
string. To do this, the flags argument is used to indicate which fields are to be 
defaulted, and the defaults argument is used to supply the default values. If the 
defaults argument is not supplied, the following default values are applied: 

• For the date group, the default is the current date. 

• For the time group, the default is 00:00:00.00. 

Optionally, you can use the defaulted-fields argument to receive information on 
which input fields were omitted and thus accepted default values. 

_ Note _ 

Because the default is the current date for the date group, if you specify 
a value of 00 with the !Y2 format, the year is interpreted as 1900. After 
January 1, 2000, the value 00 will be interpreted as 2000. 


Condition Values Returned 

SS$_NORMAL 

LIB$_DEFFORUSE 

LIB$_ENGLUSED 

LIB$_AMBDATTIM 


Normal successful completion. 

Default format used; unable to determine desired 
format. 

English used by default; unable to translate 
SYS$LANGUAGE. 

Ambiguous date/time. 
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LIB$_INCDATTIM 

LIB$_ILLFORMAT 

LIB$_INVARG 

LIB$_INVSTRDES 

LIB$_IVTIME 

LIB$_REENTRANCY 

LIB$_UNRFORCOD 

LIB$_WRONUMARG 


Incomplete date/time; missing fields with no 
defaults. 

Illegal format string; too many or not enough 
fields. 

Invalid argument; a required argument was not 
specified. 

Invalid input string descriptor. 

Invalid date/time. 

Reentrancy detected. 

Unrecognized format code. 

Wrong number of arguments. 


Any condition value returned by LIB$GET_VM, LIB$FREE_VM, LIB$FREE1 
DD, LIB$SCOPY_R_DX, SYS$NUMTIM, and SYS$GETTIM. 
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LIB$CRC—Calculate a Cyclic Redundancy Check (CRC) 

The Calculate a Cyclic Redundancy Check routine calculates the cyclic 
redundancy check (CRC) for a data stream. 


Format 

LIB$CRC crc-table ,initial-crc .stream 

Returns 


OpenVMS usage longword_unsigned 
type longword (unsigned) 

access write only 

mechanism by value 

The computed cyclic redundancy check. 


Arguments 

crc-table 

OpenVMS usage vector_longword_signed 
type longword integer (signed) 

access read only 

mechanism by reference, array reference 

The 16-longword cyclic redundancy check table created by a call to LIB$CRC_ 
TABLE. The crc-table argument is the address of a signed longword integer 
containing this table. Because this table is created by LIB$CRC_TABLE and 
then used as input in LIB$CRC, your program must call LIB$CRC_TABLE before 
it calls LIB$CRC. 

initial-crc 

OpenVMS usage longword_signed 
type longword integer (signed) 

access read only 

mechanism by reference 

Initial cyclic redundancy check. The initial-crc argument is the address of a 
signed longword integer containing the initial cyclic redundancy check. 

stream 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Data stream for which LIB$CRC is calculating the CRC. The stream argument 
is the address of a descriptor pointing to the data stream. 
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Description 

Before your program can call LIB$CRC, it must call LIB$CRC_TABLE. 
LIB$CRC_TABLE takes a polynomial as its input and builds the table that 
LIB$CRC uses to calculate the CRC. 

LIB$CRC allows your high-level language program to use the CRC instruction, 1 
which calculates the Cyclic Redundancy Check. This instruction checks the 
integrity of a data stream by comparing its state at the sending point and the 
receiving point. Each character in the data stream is used to generate a value 
based on a polynomial. The values for each character are then added together. 
This operation is performed at both ends of the data transmission, and the two 
result values compared. If the results disagree, then an error occurred during the 
transmission. 


Condition Values Returned 

None. 


Example 

For an example on how to use LIB$CRC, refer to the BASIC example at the end 
of the description of LIB$CRC_TABLE. 


1 On AXP systems, OpenVMS AXP instructions perform the equivalent operation. 
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LIB$CRC_TABLE—Construct a Cyclic Redundancy Check (CRC) 

Table 

The Construct a Cyclic Redundancy Check Table routine constructs a 16-longword 
table that uses a cyclic redundancy check polynomial specification as a bit mask. 


Format 

LIB$CRC_TABLE polynomial-coefficient ,crc-table 

Returns 

None. 

Arguments 

polynomial-coefficient 

OpenVMS usage mask_longword 
type longword (unsigned) 

access read only 

mechanism by reference 

A bit mask indicating which polynomial coefficients are to be generated by 
LIB$CRC_TABLE. The polynomial-coefficient argument is the address of an 
unsigned longword integer containing this bit mask. 

crc-table 

OpenVMS usage vector_longword_signed 
type longword integer (signed) 

access write only 

mechanism by reference, array reference 

The 16-longword table that LIB$CRC_TABLE produces. The crc-table argument 
is the address of a signed longword integer containing the table. 

Description 

The table created by LIB$CRC_TABLE can be passed to the LIB$CRC routine for 
generating the cyclic redundancy check value for a stream of characters. 

Condition Values Returned 

None. 

Example 


1 %TITLE "Demonstrate LIB$CRC and LIB$CRC_TABLE" 
%SBTTL "Declarations" 

%IDENT "1-001" 


OPTION TYPE = EXPLICIT 


DECLARE LONG 
LONG 
LONG 
STRING 
STRING 


CRC_TABLE(15) , 
CRC_VAL_1, 
CRC_VAL_2, 
DATA_1, 

DATA 2 


! CRC table array & 

I CRC for first stream & 

! CRC for second stream & 
! First data stream & 

! Second data stream 
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EXTERNAL LONG FUNCTION LIB$CRC ! Rtn to calculate CRC 

EXTERNAL SUB LIB$CRC_TABLE ! Rtn to set up table for CRC 

OPEN "SYS$INPUT:" FOR INPUT AS FILE 1% 


Initialize the CRC table. Use the CRC-16 polynomial (refer to the 
"VAX Architecture Reference Manual"). This is the polynomial used by 
DDCMP and Bisync. 


CALL LIB$CRC_TABLE( 0'120001'L, CRC_TABLE() BY REF ) 

! + 

! Get data from user. 

i _ 

LINPUT #1%, 'Enter string: ';DATA_1 
! + 

! Calc the CRC for the user's input. This CRC polynomial needs 
! an initial CRC of 0 (refer to the "VAX Architecture Reference Manual".) 

! LIB$CRC returns a longword, but only the low order word is valid 
! for this polynomial. 

i _ 

CRC_VAL_1 = LIB$CRC( CRC_TABLE() BY REF, 0%, DATA_1 ) 

CRC_VAL_1 = CRC_VAL_1 AND 32767% 

! + 

! Get more data from user. 

i _ 

LINPUT #1%, 'Enter a second string: ';DATA_2 

CRC_VAL_2 = LIB$CRC( CRC_TABLE() BY REF, 0%, DATA_2 ) 

CRC_VAL_2 = CRC_VAL_2 AND 32767% 

! + 

! Tell the user the results of the CRC comparison. 

i _ 

IF CRC_VAL_1 = CRC_VAL_2 
THEN 

PRINT "The two CRCs";CRC_VAL_1;" and ";CRC_VAL_2;" were the same" 

ELSE 

PRINT "The two CRCs";CRC__VAL_1;" and ";CRC_VAL_2;" were the different" 
END IF 

IF DATA_1 = DATA_2 
THEN 

PRINT "The two strings were the same" 

ELSE 

PRINT "The two strings were different" 

END IF 

END 
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This BASIC example program shows the use of LIB$CRC and LIB$CRC_TABLE. 
One example of the output generated by this program is as follows: 

$ RUN CRC 

Enter string: DOVE 

Enter a second string: HOSE 

The two CRCs 29915 and 29915 were the same 

The two strings were different 
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LIB$CREATE_DIR—Create a Directory 

The Create a Directory routine creates a directory or subdirectory. 


Format 


LIB$CREATE_DIR device-directory-spec [,owner-UIC] [,protection-enable] [.protection-value] 
[.maximum-versions] [.relative-volume-number] 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Arguments 

de vice-d i rectory-spec 

OpenVMS usage device_name 
type character string 

access read only 

mechanism by descriptor 

Directory specification of the directory or subdirectory that LIB$CREATE_DIR 
will create. The device-directory-spec argument is the address of a descriptor 
pointing to this directory specification. 

The format of the device-directory-spec string conforms to standard Record 
Management Services (RMS) format. This specification must contain a 
directory or subdirectory specification. It may contain a disk specification. 
SMD$:[THIS.IS.IT] is an example of a standard RMS file specification, where 
SMD$ is the disk specification and [THIS.IS.IT] is the subdirectory specification. 

This specification cannot contain a node name, file name, file type, file version, or 
wildcard characters. The maximum size of this string is 255 characters. 


owner-UIC 

OpenVMS usage uic 
type longword (unsigned) 

access read only 

mechanism by reference 

User Identification Code (UIC) identifying the owner of the created directory or 
subdirectory. The owner-UIC argument is the address of an unsigned longword 
that contains the UIC. If owner-UIC is zero, the owner UIC is that of the parent 
directory. The specified value for owner-UIC is interpreted as a 32-bit octal 
number, with two 16-bit fields: 

bits 0-15—member number 
bits 16-31—group number 

This is an optional argument. The default is the UIC of the parent directory 
except when the directory is in UIC format. For a directory in UIC format, for 
example [123,321], the UIC of the created directory is used. 
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protection-enable 

OpenVMS usage mask_word 
type word (unsigned) 

access read only 

mechanism by reference 

Mask specifying the bits of protection-value to be set. The protection-enable 
argument is the address of an unsigned word containing this protection mask. 

Figure LIB-1 shows the structure of a protection mask. Access is allowed for bits 
set to zero. 

Figure LIB-1 Structure of a Protection Mask 


World Group Owner System 



ZK-1979-GE 

Set bits in the protection-enable mask cause corresponding bits of protection- 
value to be set. Clear bits in the protection-enable mask cause corresponding 
bits of protection-value to take the value of the corresponding bit in the parent 
directory’s file protection. Bits in the parent directory’s file protection which 
indicate delete access will not cause corresponding bits of protection-value to be 
set, however. 

Following is an example of how the protection-value protection mask is defined. 


Mask Name 

Hex Number 

Value 

Protection enable 

Parent directory 

Protection value 

%XDBFF 

%X13FF 

%X37FF 

S:NONE, OiNONE, G:E, W:W 
S:RWED, 0:RWED, G:RW, W:R 
S:RWE, 0:RWE, G:RWE, W:RW 


Protection-enable is an optional argument. It should be used only when 
you wish to change protection values from the parent directory’s default file 
protection. The default for protection-enable is a mask of all zero bits, 
which results in the propagation of the parent directory’s file protection. If 
the protection-enable mask contains zeros, protection-value is ignored. 
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protection-value 

OpenVMS usage file_protection 
type word (unsigned) 

access read only 

mechanism by reference 

System/Owner/Group/World protection value of the directory you are creating. 
The protection-value argument is the address of an unsigned word which 
contains this protection mask. 

The bits of protection-value are set or cleared in the method described in the 
definition of protection-enable above. 

Protection-value is an optional argument. The default is a word of all zero bits, 
which specifies full access for all access categories. Typically, protection-value 
is not omitted unless protection-enable is also omitted. If protection-enable 
is omitted, protection-value will be ignored. 

maximum-versions 

OpenVMS usage word_unsigned 
type word (unsigned) 

access read only 

mechanism by reference 

Maximum number of versions allowed for files created in the newly created 
directories. The maximum-versions argument is the address of an unsigned 
word containing the value of the maximum number of versions. 

Maximum-versions is an optional argument. The default is the parent 
directory’s default version limit. If specified as zero, the maximum number 
of versions is not limited. 

relative-volume-number 

OpenVMS usage word_unsigned 
type word (unsigned) 

access read only 

mechanism by reference 

Relative volume number within a volume set on which the directory or 
subdirectory is created. The relative-volume-number argument is the address 
of an unsigned word containing the relative volume number. The relative- 
volume-number argument is optional. The default is arbitrary placement 
within the volume set. 


Description 

LIB$CREATE_DIR allows the caller to indicate the owner and protection of the 
created directory or subdirectory. The caller can also indicate the maximum 
number of versions of a file which will be maintained and the relative volume 
number in which the directory or subdirectory will be created. 
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Condition Values Returned 


SS$_CREATED 
SS$_N ORMAL 
LIB$_INVARG 

LIB$_INVFILSPE 


Routine successfully completed; one or more 
directories created. 

Routine successfully completed; all specified 
directories already exist. 

Invalid argument to Run-Time Library. Either 
the required argument was omitted, or device- 
directory-spec is longer than 255 characters. 
Invalid file specification. Either the file 
specification did not contain an explicit directory 
and device name, or it contained a node name, 
file name, file type, file version, or wildcard. This 
error is also produced if the device specified was 
not a disk. 


Any condition values returned by 
Any condition values returned by 
Any condition values returned by 
Any condition values returned by 
Any condition values returned by 
Any condition values returned by 


$ASSIGN. 

$DASSGN. 

$PARSE. 

$QIO. 

LIB$ANALYZE_SDESC. 

LIB$GET_EF. 
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LIB$CREATE_USER_VM_ZONE—Create User-Defined Storage Zone 

The Create User-Defined Storage Zone routine creates a new user-defined storage 
zone. 

Format 

LIB$CREATE_USER_VM_ZONE zone-id [,user-argument] [,user-allocation-procedure] 

[,user-deallocation-procedure] [,user-reset-procedure] 

[,user-delete-procedure] [,zone-name] 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Arguments 

zone-id 

OpenVMS usage identifier 
type longword (unsigned) 

access write only 

mechanism by reference 

Zone identifier. The zone-id argument is the address of a longword that receives 
the identifier of the newly created zone. 

user-argument 

OpenVMS usage user_arg 
type longword (unsigned) 

access read only 

mechanism by reference 

User argument. The user-argument argument is the address of an unsigned 
longword containing the user argument. LIB$CREATE_USER_VM_ZONE copies 
the value of user-argument and supplies the value to all user-procedures 
invoked. 

user-allocation-procedure 

OpenVMS usage procedure 
type procedure value 

access function call (before return) 

mechanism by value 

User allocation routine. 

user-deallocation-procedure 

OpenVMS usage procedure 
type procedure value 

access function call (before return) 

mechanism by value 

User deallocation routine. 


cond_value 
longword (unsigned) 
write only 
by value 
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user-reset-procedure 

OpenVMS usage procedure 
type procedure value 

access function call (before return) 

mechanism by value 

User routine invoked each time LIB$RESET_VM_ZONE is called for the zone. 

user-delete-procedure 

OpenVMS usage procedure 
type procedure value 

access function call (before return) 

mechanism by value 

User routine invoked when LIB$DELETE_VM_ZONE is called for the zone. 

zone-name 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Name to be associated with the zone being created. The optional zone-name 
argument is the address of a descriptor pointing to the zone name. If zone-name 
is not specified, the zone will not have an associated name. 


Description 

LIB$CREATE_USER_VM_ZONE creates a user-defined zone. If an error status 
is returned, the zone is not created. 

Each time that one of the heap Management Routines (LIB$GET_VM, 
LIB$FREE_VM, LIB$RESET_VM_ZONE, or LIB$DELETE_VM_ZONE) is 
called to perform an operation on a user-defined zone, the corresponding user 
routine that you supplied is used. 

You may omit any of the optional user routines. However, if you omit a routine 
and later call the corresponding heap management routine, the error status 
LIB$_INVOPEZON will be returned. 

Call Format for User Routines 

The user routines are called with arguments similar to those passed to LIB$GET 
VM, LIB$FREE_VM, LIB$RESET_VM_ZONE, or LIB$DELETE_VM_ZONE. In 
each case, the user-argument argument from LIB$CREATE_USER_VM_ZONE 
is passed to the user routine rather than a zone-id argument. 

The call format for a user get or free routine is as follows: 

user-rtn num-bytes ,base-adr ,user-argument 

num-bytes 

OpenVMS usage longword_signed 
type longword integer (signed) 

access read only 

mechanism by reference 

Number of contiguous bytes to allocate or free. The num-bytes argument is 
the address of a longword integer containing the number of bytes. The value of 
num-bytes must be greater than zero. 
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base-adr 

OpenVMS usage address 
type longword (unsigned) 

access modify 

mechanism by reference 

Virtual address of the first contiguous block of bytes allocated or freed. The 
base-adr argument is the address of an unsigned longword containing this base 
address. (This argument is write-only for a get routine, and read-only for a free 
routine.) 

user-argument 

OpenVMS usage user_arg 
type longword (unsigned) 

access read only 

mechanism by reference 

User argument. LIB$CREATE_USER_VM_ZONE copies user-argument as it is 
supplied to all user routines invoked. 

The status value returned by your routine is returned as the status value for the 
corresponding call to LIB$GET_VM or LIB$FREE_VM. 

The zone-id value that is returned can be used in calls to LIB$SHOW_VM_ 
ZONE and LIB$VERIFY_VM_ZONE. 

The call format for a user reset or delete routine is as follows: 
user-rtn user-argument 

user-argument 

OpenVMS usage user_arg 
type longword (unsigned) 

access read only 

mechanism by reference 

User argument. LIB$CREATE_USER_VM_ZONE copies user-argument as it is 
supplied to all user routines invoked. 

The status value returned by your routine is returned as the status value for the 
corresponding call to LIB$RESET_VM_ZONE or LIB$DELETE_VM_ZONE. 

Condition Values Returned 

SS$_NORMAL Normal successful completion. 

LIB$_INSVIRMEM Insufficient virtual memory. 

LIB$_INVSTRDES Invalid string descriptor for zone-name. 
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LIB$CREATE_VM_ZONE—Create a New Zone 

The Create a New Zone routine creates a new storage zone according to specified 
arguments. 


Format 


LIB$CREATE_VM_ZONE zone-id [.algorithm] [.algorithm-argument] [.flags] [,extend-size] [.initial-size] 
[.block-size] [.alignment] [.page-limit] [,smallest-block-size] [.zone-name] 

[,get-page] [.free-page] 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Arguments 


zone-id 

OpenVMS usage 

type 

access 

mechanism 


identifier 

longword (unsigned) 
write only 
by reference 


Zone identifier. The zone-id argument is the address of a longword that is set to 
the zone identifier of the newly created zone. 


algorithm 

OpenVMS usage longword_signed 
type longword integer (signed) 

access read only 

mechanism by reference 

Algorithm. The algorithm argument is the address of a longword integer that 
represents the code for one of the LIB$VM algorithms: 


1 LIB$K_VM_FIRST_FIT 

2 LIB$K_VM_QUICK_FIT 

3 LIB$K_VM_FREQ_SIZES 

4 LIB$K_VM_FIXED 


First fit 

Quick fit, lookaside list 
Frequent sizes, lookaside list 
Fixed size blocks 


If algorithm is not specified, a default of 1 (first fit) is used. 


algorithm-argument 

OpenVMS usage longword_signed 
type longword integer (signed) 

access read only 

mechanism by reference 

Algorithm argument. The algorithm-argument argument is the address of 
a longword integer that contains a value specific to the particular allocation 
algorithm. 
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Algorithm 

Value 

First fit 

Not used, may be omitted. 

Quick fit 

The number of lookaside lists used. The number of lists 
must be between 1 and 128. 

Frequent sizes 

The number of lookaside lists used. The number of lists 
must be between 1 and 16. 

Fixed size blocks 

The fixed request size (in bytes) for each get or free 
request. The request size must be greater than 0. 


The algorithm-argument argument must be specified if you are using the 
quick-fit, frequent-sizes or fixed-size-blocks algorithms. However, this argument 
is optional if you are using the first-fit algorithm. 

flags 

OpenVMS usage mask_longword 
type longword (unsigned) 

access read only 

mechanism by reference 

Flags. The flags argument is the address of a longword integer that contains flag 
bits that control various options: 


Bit Value Description 


0 LIB$M_VM_BOUNDARY_TAGS 

1 LIB$M_VM_GET_FILLO 

2 LIB$M_VM_GET_FILL1 

3 LIB$M_VM_FREE_FILLO 

4 LIB$M_VM_FREE_FILL1 

5 LIB$M_VM_EXTEND_AREA 

6 LIB$M_VM_N 0_EXTEND 

7 LIB$M_VM_TAIL_LARGE 


Boundary tags for faster freeing. 
Adds a minimum of eight bytes to 
each block. 

LIB$GET_VM; fill with bytes of 0. 

LIB$GET_VM; fill with bytes of FF. 
(hexadecimal) 

LIB$FREE_VM; fill with bytes of 0. 

LIB$FREE_VM; fill with bytes of 
FF. (hexadecimal) 

Add extents to existing areas if 
possible. 

Prevents zone from being extended 
beyond its initial size. If you specify 
this flag, you must also specify an 

initial-size. Extend-size is not 

used. 

Add larger than extend-size 
areas to the end of the area list. 
Allocations that are larger than 
the extend-size can result in new 
areas. These areas are added to 
the end of the area list. (This 
provides better memory reuse when 
allocating small and very large 
blocks from the same zone.) 


Bits 8 through 31 are reserved and must be 0. 
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This is an optional argument. If flags is omitted, the default of 0 (no fill and no 
boundary tags) is used. 


extend-size 

OpenVMS usage 

type 

access 

mechanism 


longword_signed 
longword integer (signed) 
read only 
by reference 


Zone extend size. The extend-size argument is the address of a longword integer 
that contains the number of (512-byte) pages on VAX systems or pagelets on AXP 
systems to be added to the zone each time it is extended. 


The value of extend-size must be between 1 and 1024. 


This is an optional argument. If extend-size is not specified, a default of 16 
pages on VAX systems or pagelets on AXP systems is used. 


_ Note _ 

Extend-size does not limit the number of blocks that can be allocated 
from the zone. The actual extension size is the greater of extend-size 
and the number of pages on VAX systems or pagelets on AXP systems 
needed to satisfy the LIB$GET_VM call that caused the extension. 


initial-size 

OpenVMS usage longword_signed 
type longword integer (signed) 

access read only 

mechanism by reference 

Initial size for the zone. The initial-size argument is the address of a longword 
integer that contains the number of (512-byte) pages on VAX systems or pagelets 
on AXP systems to be allocated for the zone as the zone is created. 

This is an optional argument. If you specify a value for initial-size, the value 
must be between 0 and 1024; otherwise, LIB$_INVARG is returned. If initial- 
size is not specified or is specified as 0, no pages on VAX systems or pagelets on 
AXP systems are allocated when the zone is created. The first call to LIB$GET_ 
VM for the zone allocates extend-size pages on VAX systems or pagelets on AXP 
systems. 

block-size 

OpenVMS usage longword_signed 
type longword integer (signed) 

access read only 

mechanism by reference 

Block size of the zone. The block-size argument is the address of a longword 
integer specifying the allocation quantum (in bytes) for the zone. All blocks 
allocated are rounded up to a multiple of block-size. 

The value of block-size must be a power of 2 between 8 and 512. This is an 
optional argument. If block-size is not specified, a default of 8 is used. 
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alignment 

OpenVMS usage longword_signed 
type longword integer (signed) 

access read only 

mechanism by reference 

Block alignment. The alignment argument is the address of a longword integer 
that specifies the required address alignment (in bytes) for each block allocated. 

The value of alignment must be a power of 2 between 4 and 512. This is an 
optional argument. If alignment is not specified, a default of 8 (quadword 
alignment) is used. 

page-limit 

OpenVMS usage longword_signed 
type longword integer (signed) 

access read only 

mechanism by reference 

Maximum page limit. The page-limit argument is the address of a longword 
integer that specifies the maximum number of (512-byte) pages on VAX systems 
or pagelets on AXP systems that can be allocated for the zone. The value of 
page-limit must be between 0 and 32,767. Note that part of the zone is used for 
header information. 

This is an optional argument. If page-limit is not specified or is specified as 
0, the only limit is the total process virtual address space limit imposed by 
OpenVMS. If page-limit is specified, then initial-size must also be specified. 

smallest-block-size 

OpenVMS usage longword_signed 
type longword integer (signed) 

access read only 

mechanism by reference 

Smallest block size. The smallest-block-size argument is the address of a 
longword integer that specifies the smallest block size (in bytes) that has a 
lookaside list for the quick fit algorithm. 

If smallest-block-size is not specified, the default of block-size is used. That is, 
lookaside lists are provided for the first n multiples of block-size. 

zone-name 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Name to be associated with the zone being created. The optional zone-name 
argument is the address of a descriptor pointing to the zone name. If zone-name 
is not specified, the zone will not have an associated name. 

get-page 

OpenVMS usage procedure 
type procedure value 

access read only 

mechanism by value 
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Routine that allocates memory. The number and type of the arguments to this 
routine must match those of the LIB$GET_VM_PAGE routine. If get-page is 
not specified, or if get-page is specified as 0, the LIB$GET_VM_PAGE routine is 
used to allocate memory. 

tree-page 

OpenVMS usage procedure 
type procedure value 

access read only 

mechanism by value 

Routine that deallocates memory. The number and type of the arguments to this 
routine must match those of the LIB$FREE_VM_PAGE routine. If free-page is 
not specified, or if free-page is specified as 0, the LIB$FREE_VM_PAGE routine 
is used to deallocate memory. 


Description 

LIB$CREATE_VM_ZONE creates a new storage zone. The zone identifier 

value that is returned can be used in calls to LIB$GET_VM, LIB$FREE_VM, 

LIB$RESET_VM_ZONE, LIB$DELETE_VM_ZONE, LIB$SHOW_VM_ZONE, 

LIB$VERIFY_VM_ZONE, and LIB$CREATE_USER_VM_ZONE. 

The following restrictions apply when you are creating a zone. 

• If you want the zone to be accessible from another process or processes, you 
must map the global section into the same virtual addresses in all processes. 
You can use PPL$CREATE_SHARED_MEM to map to a global section, after 
you have first called PPL$INITIALIZE. 

• The zone cannot expand; in other words, additional areas cannot be added to 
the zone. 

• The restrictions for LIB$RESET_VM_ZONE also apply to shared zones. That 
is, it is the caller’s responsibility to ensure that the caller has exclusive access 
to the zone while the reset operation is being performed. 

If an error status is returned, the zone is not created. 


Condition Values Returned 

SS$_NORMAL 

LIB$_INSVIRMEM 

LIB$_INVARG 

LIB$_INVSTRDES 


Normal successful completion. 
Insufficient virtual memory. 

Invalid argument. 

Invalid string descriptor for zone-name 
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LIB$CRF_INS_KEY—Insert Key in Cross-Reference Table 

The Insert Key in Cross-Reference Table routine inserts information about a key 
into a cross-reference table. 

Format 

UB$CRFJNS_KEY control-table ,key-string ,symbol-value .flags 

Returns 

None. 

Arguments 

control-table 

OpenVMS usage 
type 
access 
mechanism 

Cross-reference table into which LIB$CRF_INS_KEY inserts information about 
the key. The control-table argument is the address of a signed longword integer 
pointing to the cross-reference table. You must name this table each time you call 
a cross-reference routine because you can accumulate information for more than 
one cross-reference table at a time. 

key-string 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

A counted ASCII string that contains a symbol name or an unsigned binary 
longword. The key-string argument is the address of a descriptor pointing to the 
key. 

symbol-value 

OpenVMS usage longword_signed 
type longword integer (signed) 

access read only 

mechanism by reference 

Symbol value, the address of which LIB$CRF_INS_KEY inserts in the cross- 
reference table. The symbol-value argument is the address of a signed 
longword integer containing this value. Both the key and value addresses 
must be permanent addresses in the user’s symbol table. 

flags 

OpenVMS usage mask_longword 
type longword (unsigned) 

access read only 

mechanism by reference 


vector_longword_signed 
longword integer (signed) 
read only 

by reference, array reference 
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Value used in selecting the contents of the KEY2 and VAL2 fields; flags is stored 
with the entry. The flags argument is the address of an unsigned longword 
containing the flags. When preparing the output line, LIB$CRF_OUTPUT uses 
flags and the 16-bit mask in the field descriptor table to extract the data. The 
high-order bit of the word is reserved for LIB$CRF_INS_KEY. 


Description 

LIB$CRF_INS_KEY stores information to be printed in the KEY1, KEY2, VAL1, 

and VAL2 fields. When you call this routine, an entry for the key is made in the 

cross-reference table if the key is not present in the table. If the key is present, 

only the value address and value flag fields are updated. 

Using LIB$CRF_INS_KEY involves the following steps: 

• Define a table of control information, using the $CRFCTLTABLE macro. 

• Define each field of the output line, using the $CRFFIELD macro. 

• Specify the end of each set of macros that define a field in the output line, 
using the $CRFFIELDEND macro. 

• Provide data by calling LIB$CRF_INS_KEY to insert an entry for the specify 
key in the specified symbol table. This data is used to build tables in virtual 
memory. 

• Call LIB$CRF_OUTPUT, the cross-reference output routine, to summarize 
and format the data. Supply a routine that LIB$CRF_OUTPUT calls to print 
each line in the output file. Because you supply this routine, you can control 
the number of lines per page and the header lines. 

Condition Values Returned 

None. 
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LIB$CRF_INS_REF—Insert Reference to a Key in the 

Cross-Reference Table 

The Insert Reference to a Key in the Cross-Reference Table routine inserts a 
reference to a key in a cross-reference symbol table. 


Format 


LIB$CRFJNS_REF control-table ,longword-integer-key ,reference-string Jongword-integer-reference 
,ref-definition-indicator 


Returns 


None. 


Arguments 


control-table 

OpenVMS usage 

type 

access 

mechanism 


vector_longword_signed 
longword integer (signed) 
read only 

by reference, array reference 


Control table associated with this cross-reference. The control-table argument 
is the address of an array containing the control table. 


longword-integer-key 

OpenVMS usage longword_signed 
type longword integer (signed) 

access read only 

mechanism by reference 

Key referred to by LIB$CRF_INS_REF. The longword-integer-key argument is 
the address of a signed longword integer containing the key. The key is a counted 
ASCII string that contains a symbol name or an unsigned binary longword. It 
must be a permanent address in the user’s symbol table. 

reference-string 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Counted ASCII string with a maximum of 31 characters, not including the byte 
count. The reference-string argument is the address of a descriptor pointing to 
the counted ASCII string. 

longword-integer-reference 

OpenVMS usage longword_signed 
type longword integer (signed) 

access write only 

mechanism by reference 

The 16-bit value used in selecting the contents of the REF1 field. The longword- 
integer-reference argument is the address of a signed longword integer 
containing this value. When preparing the output line, LIB$CRF_OUTPUT uses 
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longword-integer-reference and the bit mask in the field descriptor table to 
extract the data. The high-order bit of the word is reserved for LIB$CRF_INS_ 
REF. 

ref-definition-indicator 

OpenVMS usage longword_signed 
type longword integer (signed) 

access read only 

mechanism by reference 

Reference/definition indicator that LIB$CRF_INS_REF uses to distinguish 
between a reference to a symbol and the definition of the symbol. The ref- 
definition-indicator argument is the address of a signed longword integer 
containing this indicator. The only difference between processing a symbol 
reference and a symbol definition is where LIB$CRF_INS_REF stores the 
information. 

The reference/definition indicator can have either of the following values: 


Symbolic Name 

Description 

crf$k_ref 

Reference to a symbol 

CRF$K_DEF 

Definition of a symbol 


Description 

LIB$CRF_INS_REF inserts a reference to a key in the cross-reference symbol 
table. If you attempt to insert reference information for a key that was not 
specified in a call to LIB$CRF_INS_KEY, LIB$CRF_INS_REF uses the address 
of the key to locate the symbol name and set the KEY1 field. Once set, either as 
a result of LIB$CRF_INS_KEY or LIB$CRF_INS_REF, the KEY1 field is never 
changed. A KEY1 field set by LIB$CRF_INS_REF has a space-filled VAL1 field 
associated with it unless it is overridden by a subsequent call to LIB$CRF_INS_ 
KEY. 

Using LIB$CRF_INS_REF involves the following steps: 

1. Define a table of control information, using the $CRFCTLTABLE macro. 

2. Define each field of the output line, using the $CRFFIELD macro. 

3. Specify the end of each set of macros that define a field in the output line, 
using the $CRFFIELDEND macro. 

4. Provide data by calling LIB$CRF_INS_REF to insert a reference to a key 
in the specified symbol table. This data is used to build tables in virtual 
memory. 

5. Call LIB$CRF_OUTPUT, the cross-reference output routine, to summarize 
and format the data. Supply a routine that LIB$CRF_OUTPUT calls to print 
each line in the output file. Because you supply this routine, you can control 
the number of lines per page and the header lines. 
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Condition Values Returned 

None. 
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LIB$CRF_OUTPUT—Output Cross-Reference Table Information 

The Output Cross-Reference Table Information routine extracts the information 
from the cross-reference tables and formats the output pages. 

Format 

LIB$CRF_OUTPUT control-table ,output-line-width ,page1 ,page2 .mode-indicator ,delete-save-indicator 

Returns 

None. 

Arguments 

control-table 

OpenVMS usage 
type 
access 
mechanism 

Control table associated with the cross-reference. The control-table argument 
is the address of an array containing the control table. The table contains the 
address of the user-supplied routine that prints the lines formatted by LIB$CRF_ 
OUTPUT. 

output-line-width 

OpenVMS usage longword_signed 
type longword integer (signed) 

access read only 

mechanism by reference 

Width of the output line. The output-line-width argument is the address of a 
signed longword integer containing the width. 

pagel 

OpenVMS usage longword_signed 
type longword integer (signed) 

access read only 

mechanism by reference 

Number of lines on the first page of the output. The pagel argument is the 
address of a signed longword integer containing this number. This allows 
the user to reserve space to print header information on the first page of the 
cross-reference. 

page2 

OpenVMS usage longword_signed 
type longword integer (signed) 

access read only 

mechanism by reference 

Number of lines per page for the other pages. The page2 argument is the address 
of a signed longword integer containing this number. 


vector_longword_signed 
longword integer (signed) 
read only 

by reference, array reference 


LIB-53 


LIB$CRF_OUTPUT 


mode-indicator 

OpenVMS usage longword_signed 
type longword integer (signed) 

access read only 

mechanism by reference 

Output mode indicator. The mode-indicator argument is the address of a signed 
longword integer containing the mode indicator. 

This indicator allows the user to select which of three output modes is desired. 


Output Mode 

Description 

CRF$K_VALUES 

Only the value and key fields are to be printed. 
LIB$CRF_OUTPUT creates multiple columns across 
the page. Each column consists of the KEY1, KEY2, 
VAL1, and VAL2 fields. A minimum of one space 
between each column is guaranteed. 

CRF$K_VALS_REFS 

Requests a cross-reference summary that has no 
column space saved for a defining reference. If the user 
inserted a reference with the CRF$K_DEF indicator, 
the entry is ignored. 

CRF$K_DEFS_REFS 

Requests a cross-reference summary with the first 
REF1 and REF2 fields used only for definition 
references. If no definition reference is provided, 
the fields are space filled. 


delete-save-indicator 

OpenVMS usage longword_signed 
type longword integer (signed) 

access read only 

mechanism by reference 

Delete/save indicator which LIB$CRF_OUTPUT uses to determine whether the 
table’s built-in accumulating symbol information is to be saved or deleted once the 
cross-reference is produced. The delete-save-indicator argument is the address 
of a signed longword integer containing the delete/save indicator. 

The indicator can be either of the following: 

CRF$K_SAVE To preserve the tables for subsequent processing 

CRF$K_DELETE To delete the tables 


Description 

LIB$CRF_OUTPUT can format output lines for three types of cross-reference 
listings. 

1. A summary of symbol names and their values, as shown in Figure LIB—2. 

2. A summary of symbol names, their values, and the names of modules that 
refer to the symbol, as shown in Figure LIB-3. 

3. A summary of symbol names, their values, the name of the defining module, 
and the names of those modules that refer to the symbol, as shown in 
Figure LIB—4. 
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Figure LIB-2 Summary of Symbol Names and Values 


+-+ 

! Symbols By Name ! 
+-+ 


Symbol 


BAS$INSTR 
BAS $IN_D_R 
BAS $IN_F_R 
BAS $IN_L_R 
BAS$IN_T_DX 
BAS $IN_W_R 
BAS$IO_END 
BAS$LINKAGE 
BAS $LINPUT 
BAS$MAT INPUT 


Value 


000020B0-RU 

000021F0-RU 

000021E8-RU 

000021E0-RU 

000021F8-RU 

000021D8-RU 

000021D0-RU 

00001674-R 

000021A8-RU 

00002268-RU 


Symbol 


BAS$SCRATCH 

BAS $ STATUS 

BAS$STR_D 

BAS$STR_F 

BAS$STR_L 

BAS$UNLOCK 

BAS $ UPDATE 

BAS $UPDATE_COUN 

BAS$VAL_D 

BAS$VAL F 


Value 


00002308-RU 

00002338-RU 

000020C0-RU 

000020B8-RU 

000020C8-RU 

00002310-RU 

000022E8-RU 

000022F0-RU 

00002110-RU 

00002108-RU 

ZK-1973-GE 


Figure LIB-3 Summary of Symbol Names, Values, and Name of Referring 
Modules 


Symbol 

Value 

Referenced By 


BAS$K DIVBY ZER 

0000003D 

ALLGBL 

BAS$ERROR 

BAS$K DUPKEYDET 

00000086 

BAS$POWDJ 

BAS$POWRJ 

ALLGBL 

BAS$POWII 

BAS$POWRR 

BAS $ $ SIGNAL 10 

BAS$K_ENDFILDEV 

0000000B 

ALLGBL 

BAS$$REC PROC 

BAS$K ENDOF STA 

0000006C 

BAS$$UDF RL 
ALLGBL 
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Figure LIB-4 Summary Indicating Defining Module 


Symbol 

Value 

Defined By 

Referenced By ... 

LIB$FREE VM 

0001E185-R 

LIB$VM 

ALLGBL 

LIB$GET COMMAND 

0001E2B0-R 

LIB$GET INPUT 

BAS$MARGIN 

BAS$XLATE 

FOR$VM 

STR$APPEND 
STR$DUPL CHAR 
STR$REPLACE 

ALLGBL 

LIB$GET COMMON 

0001E4D6-R 

LIB$COMMON 

ALLGBL 


ZK-1971—GE 
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Regardless of the format of the output, LIB$CRF_OUTPUT considers the output 
line as consisting of six different field types. 


KEYl 

Is the first field in the line. It contains a symbol 
name. 

KEY2 

Is the second field in the line. It contains a set of 
flags (for example, -R) that provide information 
about the symbol. 

VAL1 

Is the third field in the line. It contains the value 
of the symbol. 

VAL2 

Is the fourth field in the line. It contains a set of 
flags describing VAL1. 

REF1 and REF2 fields 

Within each REF1 and REF2 pair, REF1 provides 
a set of flags and REF2 provides the name of a 
module that references the symbol. 


Any of these fields can be omitted from the output. 
For example: 


Symbol Value Symbol Value 

BAS5INSTR 000020B0-RU BAS$SCRATCH 00002308-RU 

KEY1 VAL1 VAL2 KEY1 VAL1 VAL2 

Symbol Value Defined By Referenced By ... 

LIB$FREE_VM 0001E185-R LIB$VM ALLGBL 

KEY1 VAL1 VAL2 REF2 REF2 

(CRF$K_DEF) (CRF$K_REF) 

Condition Values Returned 

None. 
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LIB$CURRENCY—Get System Currency Symbol 

The Get System Currency Symbol routine returns the system’s currency symbol. 

Format 

LIB$CURRENCY currency-string [,resultant-length] 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Arguments 

currency-string 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor 

Currency symbol. The currency-string argument is the address of a descriptor 
pointing to the currency symbol. 

resultant-length 

OpenVMS usage word_unsigned 
type word (unsigned) 

access write only 

mechanism by reference 

Number of characters that LIB$CURRENCY has written into the currency¬ 
string argument, not counting padding in the case of a fixed-length string. 

The resultant-length argument is the address of an unsigned word containing 
the length of the currency symbol. If the input string is truncated to the size 
specified in the currency-string argument, resultant-length is set to this size. 
Therefore, resultant-length can always be used by the calling program to access 
a valid substring of currency-string. 

Description 

LIB$CURRENCY attempts to translate the logical name SYS$CURRENCY as 
a process, group, or system logical name, in that order. If the translation fails, 
the routine returns the United States currency symbol ($). If the translation 
succeeds, the text produced is returned. Thus, a system manager can define 
SYS$CURRENCY as a system-wide logical name to provide a default for all 
users, and an individual user with a special need can define SYS$CURRENCY as 
a process logical name to override the system default. 

For example, if you wish to use the British pound sign as the currency symbol 
within your process, but wish to leave the dollar sign as the system’s default, 
define SYS$CURRENCY to be the pound sign (£) in your process logical name 
table. After this, any call to LIB$CURRENCY within your process returns the 
pound sign (£), while any call outside your process returns the dollar sign ($). 
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Condition Values Returned 

SS$_NORMAL 

LIB$_STRTRU 

LIB$_FATERRLIB 


LIB$_IN S VIRMEM 

LIB$_INVSTRDES 


Routine successfully completed. 

Successfully completed, but the currency string 
was truncated. 

Fatal internal error. An internal consistency 
check has failed. This usually indicates an 
internal error in the Run-Time Library and 
should be reported to Digital in a Software 
Performance Report (SPR). 

Insufficient virtual memory. A call to LIB$GET_ 
VM has failed because your program has 
exceeded the image quota for virtual memory. 

Invalid string descriptor. A string descriptor has 
an invalid value in its DSC$B_CLASS field. 


Example 


10 ! + 

! This BASIC program uses LIB$CURRENCY to 
! return the default system currency symbol. 

i _ 

OUTLEN = 1 

CALL LIB$CURRENCY (CURR$, OUTLEN) 

PRINT CURR$ 

99 END 


The BASIC program listed above uses LIB$CURRENCY to display the system 
currency symbol default. The output generated by the program is a dollar sign 
($). 
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LIB$CVT_DX__DX—General Data Type Conversion Routine 

The General Data Type Conversion routine converts an OpenVMS standard 
atomic or string datum described by a source descriptor to another OpenVMS 
standard atomic or string datum described by a destination descriptor. This 
conversion is supported over a subset of the OpenVMS standard data types. 

Format 

UB$CVT_DX_DX source-item ,destination-item [,word-integer-dest-length] 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Arguments 

source-item 

OpenVMS usage unspecified 
type unspecified 

access read only 

mechanism by descriptor 

Source item to be converted by LIBCVT_DX_DX. The source-item argument is 
the address of a descriptor pointing to the source item to be converted. The type 
of the item to be converted is contained in the descriptor. 

The combinations of class and data type of the source descriptor are restricted as 
described in Figures LIB-5, LIB-6, and Table LIB-1. 

destination-item 

OpenVMS usage unspecified 
type unspecified 

access write only 

mechanism by descriptor 

Destination of the conversion. The destination-item argument is the address of 
a descriptor pointing to the destination item. The destination descriptor specifies 
the data type to which the source item is converted. 

The combinations of class and data type of the destination descriptor are 
restricted as described in Figures LIB-5, LIB-6, and Table LIB—1. 

word-integer-dest-length 

OpenVMS usage word_unsigned 
type word (unsigned) 

access write only 

mechanism by reference 

Length in bytes of the destination item (when that item is a string) that has 
been converted by LIB$CVT_DX_DX, not including any space filling. The 
word-integer-dest-length argument contains the address of an unsigned word 
containing this length. 


cond_value 
longword (unsigned) 
write only 
by value 
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If the destination string is truncated, the returned length reflects the truncation. 
This word can be used by the calling program to determine if truncation has 
occurred or to extract the exact length of the string when the string contains 
space filling. 


Description 

LIB$CVT_DX_DX is a universal conversion utility routine. Although some of 
the functions of this routine may be found in other Run-Time Library routines, 
LIB$CVT_DX_DX packages the conversion functions with a general interface. 
Because of this general interface, the calling program does not have to specify 
what conversion should be done for which data type. 

Refer to LIB$CVTxTB if you want to convert the ASCII text string representation 
of a decimal, hexadecimal, or octal number into a binary represenation. 

The description of this routine has been divided into the following parts: 

• Guidelines for Using LIB$CVT_DX_DX 

• Use of Numeric Byte Data Strings 

Guidelines for Using LIB$CVT_DX_DX 

The data type and descriptor class of the source and destination arguments 
determine how LIB$CVT_DX_DX performs the conversion, according to the rules 
listed below. 

• Conversion is defined over three sets of data types: atomic, string, and 
numeric byte data strings (NBDS). (For more information about numeric 
byte data strings, see the next section “Use of Numeric Byte Data Strings.”) 
Although the set of data types in NBDS is actually a subset of the atomic and 
string data types, the three sets are mutually exclusive in this routine. 

• Scale is applied when indicated in the descriptor (DSC$K_CLASS_SD only) 
and scaling is defined for the data type. 

• No language-specific semantics are applied, such as BASIC scale for DSC$K_ 
DTYPE_D. 

• Some conversions must use intermediate values to arrive at the destination 
requested. Although some loss of speed is inevitable, intermediate values will 
not cause a loss of precision. 

• Results are always rounded instead of truncated, except for the case described 
below. Note that loss of precision or range may be inherent in the destination 
data type or in the NBDS destination size. No errors are reported if there is 
a loss of precision or range as a result of destination data type. 

• When the destination is an NBDS, and has fixed-string semantics, then if the 
source does not fill the destination, the destination is padded with blanks. 

• When the source and destination are both NBDS, and no scaling is requested, 
then a straight copy is done without translation or conversion, and truncation 
is possible. If scaling is requested, then a conversion takes place as defined in 
Table LIB-1. 

• When the source is an NBDS and the destination is non-NBDS, if there is an 
invalid character in the source, or the value is outside the range that can be 
represented by the destination, then LIB$_INVNBDS is returned. 

• Attempts to convert a negative value to an unsigned data type cause the 
LIB$_INVCVT error to be returned. 
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• If the destination is an NBDS of class DSC$K_CLASS_D, then a new string 
of appropriate size will be allocated for it if necessary. 

• Invalid conversions resulting in an error produce an unpredictable result. 

Use of Numeric Byte Data Strings 

For simplicity, and to define a generic numeric string that LIB$CVT_DX_DX 
understands to be a numeric string, the set Numeric Byte Data String (NBDS) is 
defined to be the set of descriptors given in Figure LIB-5. 

Figure LIB-5 Acceptable Subset of OpenVMS Standard Data Types 


DSC$K_DTYPE_yyy 

DSC$K_CLASS_xxx 

A 

D 

NCA 

S 

SD 

VS 

B 







BU 

X 


X 




T 

X 

X 

X 

X 

X 

X 

VT 






X 


Note: An array will have the semantics of a fixed string. NBDS must have the format defined later. 
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The combination of data type and descriptor class determines whether an 
argument is an NBDS. Figure LIB—6 shows the combinations of descriptor class 
and data type (as specified in the fields of the descriptor) that LIB$CVT_DX_DX 
recognizes. The combinations marked NBDS are considered NBDS’s. 

For example, LIB$CVT_DX_DX treats the combination DSC$K_DTYPE_B 
/DSC$K_CLASS_S (unsigned byte scalar) as an atomic data type. However, 
the routine considers DSC$K_DTYPE_BU/DSC$K_CLASS_NCA (noncontiguous 
array of unsigned bytes) to be an NBDS. 

A destination NBDS is always left-justified. 

If a destination NBDS requires more than 50 digits for its format (including the 
sign, if any), then it is expressed in exponential format. 

For a conversion of NBDS to NBDS, this format is used if scaling is requested. 
Otherwise, a straight copy is done. The format of a source NBDS is the same as 
the format defined for the input argument inp in OTS$_CVT_T_z, with bits 0, 2, 
and 4 set in the flags argument. That is, blanks are ignored, underflow causes 
an error and tabs are ignored. 

Table LIB-1 defines the format of a destination NBDS. 
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Figure LIB-6 Data Types Accepted by LIB$CVT_DX_DX 


From: 

To: 


Text (Decimal) 

Longword 

Text (Hexadecimal) 

Longword 

Text (Octal) 

Longword 

Text (Binary) 

Longword 

Text (Signed Integer) 

Longword 

Text (Logical) 

Longword 

Text (Octal) 

Longword 

Text (Hexadecimal) 

Longword 

Text 

D_floating 

Text 

F_floating 

Text 

G_floating 

Text 

H_floating 





Longword 

Text (Binary) 

Longword 

Text (Signed Integer) 

Longword 

Text (Logical) 

Longword 

Text (Octal) 

Longword 

Text (Hexadecimal) 
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Table LIB-1 Destination NBDS Formats 


Source Data Type 

Destination NBDS Format 1 

Byte integer (signed) 

sdigits 

Byte (unsigned) 

sdigits 

Word integer (signed) 

sdigits 

Word (unsigned) 

digits 

Longword integer (signed) 

sdigits 

Longword (unsigned) 

digits 

Quadword integer (signed) 

sdigits 

D_floating 

s0.min(16,w-7)E(+ or —)nn 

F_floating 

s0.min( 7,w-7)E(+ or -)nn 

G_floating 

s0.min(15,w-8)E(+ or -)nnn 

H_floating 

s0.min(33,w-9)E(+ or -)nnnn 

NBDS 

s0.min(33,w-9)E(+ or -)nnnn 

Decimal string 

sdigits (as defined by VAX architecture) 

1 digits—Digits 0 through 9, and a decimal point only if source descriptor specifies DSC$B_SCALE less 
than 0. 

w—Width of destination in bytes, 
s—Sign. For positive numbers the sign is implied, 
min—Minimum of two values. 


Two array descriptors, DSC$K_CLASS_A and DSC$K_CLASS_NCA, are 
supported for specific languages that describe strings using these mechanisms. 

• DSC$B_DIMCT = 1—Only one-dimensional arrays are recognized. 

• DSC$W_LENGTH = 1—The length of each array element must be a byte. 

• DSC$L_ARSIZE less than or equal to 65,535—The total size of the array 
must be less than 65,535 bytes. 

• If DSC$L_ARSIZE = 0, the array has a length of zero. 

• DSC$L_S1 = 1—The stride of an array passed by a noncontiguous array 
descriptor must be 1. That is, even if the class of the array’s descriptor is 
noncontiguous array (NCA), the array itself must be contiguous. 

• An array is written with the semantics of a fixed string. 

For more information about the semantics of writing output strings, see the 
OpenVMS RTL String Manipulation (STR$) Manual. 

If the calling program passes a descriptor to LIB$CVT_DX_DX that does not 
comply with Figure LIB-6, one of the following error messages is returned: 

LIB$_INVDTYDSC 

LIB$_INVCLADSC 

LIB$_INVCLADTY 

LIB$_INVNBDS 
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Condition Values Returned 

SS$_N ORMAL 
LIB$_DECOVF 
LIB$_FLTOVF 
LIB$_FLTUND 
LIB$_INVCLADSC 

LIB$_INVCLADTY 


LIB$_INVCVT 


LIB$_INVDTYDSC 

LIB$_INTOVF 

LIB$_INVNBDS 


LIB$_OUTSTRTRU 


LIB$_ROPRAND 


Routine successfully completed. 

Packed decimal overflow error. Severe error. 
Floating overflow error. Severe error. 

Floating underflow error. Severe error. 

Invalid class in descriptor. This class of 
descriptor is not supported. Severe error. 

Invalid class and data type in descriptor. This 
class and data type combination is not supported. 
Severe error. 

If the source value is negative and the 
destination data type is unsigned, this error 
is returned. 

Invalid data type in descriptor. This data type is 
not supported. Severe error. 

Integer overflow error. Severe error. 

Invalid NBDS. There is an invalid character 
in the input, or the value is outside the range 
that can be represented by the destination, or 
the NMDS descriptor is invalid. This error is 
also signaled when the array size of an NBDS is 
larger than 65,535 bytes or the array is multi¬ 
dimensional. 

Output string truncated. This is returned only 
when NBDS is both source and destination and 
no scaling is requested. The result is truncated. 
Reserved operand error. Severe Error. 
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LIB$CVT_FROM_INTERNAL_TIME—Convert Internal Time to 

External Time 

The Convert Internal Time to External Time routine converts an internal 
OpenVMS system time (either absolute or delta) into an external time. 


Format 


LIB$CVT_FROM_INTERNAL_TIME operation ,resultant-time [,input-time] 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Arguments 


operation 

OpenVMS usage 

type 

access 

mechanism 


function_code 
longword (unsigned) 
read only 
by reference 


The conversion to be performed. The operation argument is the address of an 
unsigned longword containing the operation. The following table shows valid 
values for operation. 


Operation 

Return Range 

Type 

LIB$K_MONTH_OF_YEAR 

1 to 12 

Absolute 

LIB$K_DAY_OF_YEAR 

1 to 366 

Absolute 

LIB$K_HOUR_OF_YEAR 

1 to 8784 

Absolute 

LIB$K_MINUTE_OF_YEAR 

1 to 527,040 

Absolute 

LIB$K_SECOND_OF_YEAR 

1 to 31,622,400 

Absolute 

LIB$K_DAY_OF_MONTH 

1 to 31 

Absolute 

LIB$K_HOUR_OF_MONTH 

1 to 744 

Absolute 

LIB$K_MINUTE_OF_MONTH 

1 to 44,640 

Absolute 

LIB$K_SECOND_OF_MONTH 

1 to 2,678,400 

Absolute 

LIB$K_DAY_OF_WEEK 

1 to 7 

Absolute 1 

LIB$K_HOUR_OF_WEEK 

1 to 168 

Absolute 2 

LIB$K_MINUTE_OF_WEEK 

1 to 10,080 

Absolute 3 

LIB$K_SECOND_OF_WEEK 

1 to 604,800 

Absolute 4 

LIB$K_HOUR_OF_DAY 

0 to 23 

Absolute 

LIB$K_MINUTE_OF_DAY 

0 to 1439 

Absolute 


x Day 1 is Monday 

2 Hours since midnight on previous Monday 

3 Minutes since midnight on previous Monday 

4 Seconds since midnight on previous Monday 
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Operation 

Return Range 

Type 

LIB$K_SECOND_OF_DAY 

0 to 86,399 

Absolute 

LIB$K_MINUTE_OF_HOUR 

0 to 59 

Absolute 

LIB$K_SECOND_OF_HOUR 

0 to 3599 

Absolute 

LIB$K_SECOND_OF_MINUTE 

0 to 59 

Absolute 

LIB$K_JULIAN_DATE 

Julian date 

Absolute 5 

LIB$K_DELTA_WEEKS 


Delta 6 

LIB$K_DELTA_DAYS 


Delta 7 

LIB$K_DELTA_HOURS 


Delta 8 

LIB$K_DELTA_MINUTES 


Delta 9 

LIB$K_DELTA_SECONDS 


Delta 10 

5 Number of days since system zero time (17- 
6 Whole weeks 

7 Whole days 

8 Whole hours 

9 Whole minutes 

10 Whole seconds 

-Nov-1858) 



resultant-time 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access write only 

mechanism by reference 

The external time that results from the conversion. The resultant-time 
argument is the address of an unsigned longword containing the result. 

input-time 

OpenVMS usage date_time 
type quadword (unsigned) 

access read only 

mechanism by reference 

Optional absolute or delta time to be converted. The input-time argument is 
the address of an unsigned quadword containing the time. If you do not supply a 
value for input-time, the current system time is used. 


Description 

LIB$CVT_FROM_INTERNAL_TIME converts an internal OpenVMS system 
time (either absolute or delta) into an external time. The operation argument 
specifies the conversion. LIB$CVT_FROM_INTERNAL_TIME converts the value 
of input-time (or the current system time if input-time is not supplied) into one 
of the external formats listed in the operation argument description. LIB$CVT_ 
FROM_INTERNAL_TIME then places the result into resultant-time. 
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Condition Values Returned 

LIB$_NORMAL 

LIB$_IVTIME 

LIB$_WRONUMARG 

LIB$_INVOPER 

LIB$_ABSTIMREQ 

LIB$_DELTIMREQ 


Normal successful completion. 

Invalid time. 

Incorrect number of arguments. 

Invalid operation. 

Absolute time required but delta time supplied. 
Delta time required but absolute time supplied. 
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LIB$CVTF_FROMJNTERNAL_TIME—Convert Internal Time to 

External Time (F-Floating Point 
Value) 

The Convert Internal Time to External Time (F-Floating Point Value) routine 
converts a delta internal OpenVMS system time into an external F-floating time. 

Format 

LIB$CVTF_FROM_INTERNAL_TIME operation ,resultant-time ,input-time 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Arguments 

operation 

OpenVMS usage function_code 
type longword (unsigned) 

access read only 

mechanism by reference 

The conversion to be performed. The operation argument is the address of an 
unsigned longword specifying the operation. Valid values for operation are the 
following: 


Operation 

Interpretation 

LIB$K_DELTA_WEEKS_F 

Fractional weeks 

LIB$K_DELTA_DAYS_F 

Fractional days 

LIB$K_DELTA_HOURS_F 

Fractional hours 

LIB$K_DELTA_MINUTES_F 

Fractional minutes 

LIB$K_DELTA_SECONDS_F 

Fractional seconds 


resultant-time 

OpenVMS usage floating_point 
type F_floating 

access write only 

mechanism by reference 

The external time that results from the conversion. The resultant-time 
argument is the address of an F-floating point value containing the result. 

input-time 

OpenVMS usage date_time 
type quadword (unsigned) 

access read only 

mechanism by reference 
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Delta time to be converted. The input-time argument is the address of an 
unsigned quadword containing the time. 


Description 

LIB$CVTF_FROM_INTERNAL_TIME converts a delta internal OpenVMS system 
time into an external F-floating point time. The operation argument specifies 
the conversion. LIB$_CVTF_FROM_INTERNAL_TIME converts the value of 
input-time into one of the external formats listed in the operation argument 
description. LIB$_CVTF_FROM_INTERNAL_TIME then places the result into 
resultant-time. 


Condition Values Returned 

LIB$_N ORMAL 

LIB$_DELTIMREQ 

LIB$_IVTIME 

LIB$_WRONUMARG 

LIB$_INVOPER 


Normal successful completion. 

Delta time required but absolute time supplied. 
Invalid time. 

Incorrect number of arguments. 

Invalid operation. 
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LIB$CVT_TO_INTERNAL_TIME—Convert External Time to Internal 

Time 

The Convert External Time to Internal Time routine converts an external time 
interval into an OpenVMS internal format delta time. 


Format 

UB$CVT_TO_INTERNAL_TIME operation ,input-time ,resultant-time 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Arguments 


operation 

OpenVMS usage 

type 

access 

mechanism 


function_code 
longword (unsigned) 
read only 
by reference 


The conversion to be performed. The operation argument is the address of an 
unsigned longword specifying the operation. Valid values for operation are the 
following: 


Operation 

Interpretation 

LIB$KJDELTA_WEEKS 

LIB$K_DELTA_DAYS 

LIB$K_DELTA_HOURS 

LIB$K_DELTA_MINUTES 

LIB$K_DELTA_SECONDS 

Whole weeks in delta time 

Whole days in delta time 

Whole hours in delta time 

Whole minutes in delta time 

Whole seconds in delta time 


input-time 

OpenVMS usage varying_arg 
type longword (signed) 

access read only 

mechanism by reference 

Delta time to be converted. The input-time argument is the address of this 
input time. The value you supply for input-time must neither be negative nor 
greater than 10,000 days. 

resultant-time 

OpenVMS usage date_time 
type quadword (unsigned) 

access write only 

mechanism by reference 
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The OpenVMS internal format delta time that results from the conversion. The 
resultant-time argument is the address of an unsigned quadword containing the 
result. 

Description 

LIB$CVT_TO_INTERNAL_TIME converts an external time interval, such as 
three weeks, into an OpenVMS internal format delta time. The operation 
argument specifies the conversion. LIB$_CVT_TO_INTERNAL_TIME converts 
the value of input-time into one of the internal format delta times listed in the 
operation argument description. LIB$_CVT_TO_INTERNAL_TIME then places 
the result into resultant-time. 

Condition Values Returned 

LIB$_NORMAL Normal successful completion. 

LIB$_IVTIME Invalid time. 

LIB$_WRONUMARG Incorrect number of arguments. 

LIB$_INVOPER Invalid operation. 
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LIB$CVTF_TO_INTERNAL__TIME—Convert External Time to Internal 

Time (F-Floating Point Value) 

The Convert External Time to Internal Time (F-Floating Point Value) routine 
converts an external time interval into an OpenVMS internal format F-floating 
delta time. 

Format 

LIB$CVTF_TOJNTERNAL_TIME operation ,input-time ,resultant-time 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Arguments 

operation 

OpenVMS usage function_code 
type longword (unsigned) 

access read only 

mechanism by reference 

The conversion to be performed. The operation argument is the address of an 
unsigned longword specifying the operation. Valid values for operation are the 
following: 


Operation 

Interpretation 

LIB$K_DELTA_WEEKS_F 

Fractional weeks 

LIB$K_DELTA_DAYS_F 

Fractional days 

LIB$K_DELTA_HOURS_F 

Fractional hours 

LIB$K_DELTA_MINUTES_F 

Fractional minutes 

LIB$K_DELTA_SECONDS_F 

Fractional seconds 


input-time 

OpenVMS usage varying_arg 
type F_floating 

access read only 

mechanism by reference 

Delta time to be converted. The input-time argument is the address of this 
input time. The value you supply for input-time must neither be negative nor 
greater than 10,000 days. 

resultant-time 

OpenVMS usage date_time 
type quadword (unsigned) 

access write only 

mechanism by reference 
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The OpenVMS internal format delta time that results from the conversion. The 
resultant-time argument is the address of an unsigned quadword containing the 
result. 

Description 

LIB$CVTF_TO_INTERNAL_TIME converts an external time interval, such as 3.5 
weeks, into an OpenVMS internal format F-floating delta time. The operation 
argument specifies the conversion. LIB$_CVTF_TO_INTERNAL_TIME converts 
the value of input-time into one of the internal format delta times listed in 
the operation argument description. LIB$_CVTF_TO_INTERNAL_TIME then 
places the result into resultant-time. 

Condition Values Returned 

LIB$_NORMAL Normal successful completion. 

LIB$_IVTIME Invalid time. 

LIB$_WRONUMARG Incorrect number of arguments. 

LIB$_INVOPER Invalid operation. 
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LIB$CVT_xTB—Convert Numeric Text to Binary 

The Convert Numeric Text to Binary routines return a binary representation of 
the ASCII text string representation of a decimal, hexadecimal, or octal number. 

Format 

LIB$CVT_DTB byte-count ,numeric-string .result 
LIB$CVT_HTB byte-count .numeric-string .result 
LIB$CVT_OTB byte-count .numeric-string .result 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Arguments 

byte-count 

OpenVMS usage longword_signed 
type longword integer (signed) 

access read only 

mechanism by value 

Byte count of the input ASCII text string. The byte-count argument is a signed 
longword integer containing the byte count of the input string. 

numeric-string 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by reference 

ASCII text string representation of a decimal, hexadecimal, or octal number 
which LIB$CVTxTB converts to binary representation. The numeric-string 
argument is the address of a character string containing this input string to be 
converted. 

result 

OpenVMS usage longword_signed 
type longword integer (signed) 

access write only 

mechanism by reference 

Binary representation of the input string. The result argument is the address of 
a signed longword integer containing the converted string. 


cond_value 
longword (unsigned) 
write only 
by value 
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Description 

LIB$CVT_DTB converts the ASCII text string representation of a decimal 
number into binary representation. LIB$CVT_HTB converts the ASCII text 
string representation of a hexadecimal number into binary representation. 
LIB$CVT_OTB converts the ASCII text string representation of an octal number 
into binary representation. 


_ Note _ 

LIB$CVT_DTB, LIB$CVT_HTB, and LIB$CVT_OTB are intended to 
be called primarily from BLISS and MACRO programs. Therefore, the 
routines expect input scalar arguments to be passed by value and strings 
by reference. Blanks are invalid characters. 


Condition Values Returned 

1 Routine successfully completed. 

0 Nonradix character in the input string or a sign 

in any position other than the first character. 
Blanks and tabs are invalid characters. An 
overflow from 32 bits (unsigned) will cause an 
error. 
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LIB$CVT_VECTIM—Convert Seven-Word Vector to Internal Time 

The Convert Seven-Word Vector to Internal Time routine converts a seven-word 
vector into an OpenVMS internal format delta or absolute time. 


Format 

LIB$CVT_VECTIM input-time ,resultant-time 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Arguments 


input-time 

OpenVMS usage 

type 

access 

mechanism 


vector_word_unsigned 
word (unsigned) 
read only 

by reference, array reference 


Time to be converted. The input-time argument is the address of a seven-word 
structure containing this time. This vector directly corresponds to a $NUMTIM 
timbuf structure. The following diagram depicts the fields in this structure. 


31 15 0 


Month of Year 

Year Since 0 

Hour of Day 

Day of Month 

Second of Minute 

Minute of Hour 


Hundredths of Second 


ZK-7968-GE 

Input-time can represent an absolute or a delta time. In order for input-time 
to represent a delta time, the year since 0 and month of year fields must equal 
zero. If those fields do not equal zero, an absolute time is returned. 

resultant-time 

OpenVMS usage date_time 
type quadword (unsigned) 

access write only 

mechanism by reference 

The OpenVMS internal format delta or absolute time that results from the 
conversion. The resultant-time argument is the address of an unsigned 
quadword containing the result. 
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Description 

LIB$CVT_VECTIM converts a seven-word vector (in the format output by the 
system service SYS$NUMTIM) into an OpenVMS internal format delta or 
absolute time. LIB$CVT_VECTIM then places the result into resultant-time. 

See the OpenVMS System Services Reference Manual for more information about 
SYS$NUMTIM. 

Condition Values Returned 

LIB$_NORMAL Normal successful completion. 

LIB$_IVTIME Invalid time. 

LIB$_WRONUMARG Incorrect number of arguments. 
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LIB$DATE_TIME—Date and Time Returned as a String 

The Date and Time Returned as a String routine returns the OpenVMS system 
date and time in the semantics of a user-provided string. 

Format 

LIB$DATE_TIME date-time-string 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Argument 

date-time-string 

OpenVMS usage time_name 
type character string 

access write only 

mechanism by descriptor 

Destination string into which LIB$DATE_TIME writes the system date and time. 
The date-time-string argument is the address of a descriptor pointing to the 
destination string. This string is 23 characters long; its format is as follows: 

dd-mmm-yyyy hh:mm:ss.hh 

Condition Values Returned 

SS$_N ORMAL 
LIB$_STRTRU 
LIB$_INSVIRMEM 

LIB$_INVSTRDES 


Example 

10 ! + 

! This BASIC program demonstrates the 
! use Of LIB$DATE_TIME. 

i _ 

CALL LIB$DATE_TIME(DSTSTR$) 

PRINT DSTSTR$ 

99 END 

This BASIC program uses LIB$DATE_TIME to display the current system date 
and time. The output generated by one run of this program was as follows: 

26-JUL-1994 13:41:22.67 


Routine successfully completed. 

Success, but destination string was truncated. 

Insufficient virtual memory. A call to LIB$GET_ 
VM has failed because your program has 
exceeded the image quota for virtual memory. 

Invalid string descriptor. A string descriptor has 
an invalid value in its DSC$B CLASS field. 


cond_value 
longword (unsigned) 
write only 
by value 
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LIB$DAY—Day Number Returned as a Longword Integer 

The Day Number Returned as a Longword Integer routine returns the number 
of days since the system zero date of November 17, 1858, or the number of days 
from November 17, 1858, to a user-supplied date. 

Format 

UB$DAY number-of-days [,user-time] [,day-time] 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Arguments 

number-of-days 

OpenVMS usage longword_signed 
type longword integer (signed) 

access write only 

mechanism by reference 

Number of days since the system zero date. The number-of-days argument is 
the address of a signed longword integer containing the day number. 

user-time 

OpenVMS usage date_time 
type quadword (unsigned) 

access read only 

mechanism by reference 

User-supplied time, in 100-nanosecond units. The user-time argument is the 
address of a signed quadword integer containing the user time. A positive value 
indicates an absolute time, while a negative value indicates a delta time. This is 
an optional argument. If omitted, the default is the current system time. This 
quadword time value is obtained by calling the system service SYS$BINTIM. 

If time is passed as zero by value, the numeric value for the current day 
is returned. If time is passed as a zero by reference, the number returned 
represents the day of November 17, 1858, rather than the current day. 

day-time 

OpenVMS usage longword_signed 
type longword integer (signed) 

access write only 

mechanism by reference 

Number of 10-millisecond units since midnight of the user-time argument. 

The day-time argument is the address of a signed longword integer into which 
LIB$DAY writes this number of units. 


cond_value 
longword (unsigned) 
write only 
by value 
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Description 

LIB$DAY returns the number of days since the system zero date of November 17, 
1858. Optionally, the caller can supply a time in system time format to be used 
instead of the current system time. In this case, LIB$DAY returns the number of 
days from November 17, 1858, to the user-supplied date. 

The number of 10-millisecond units since midnight is an optional return 
argument. 


_ Note _ 

If the caller supplies a quadword time, it is not verified. If it is negative 
(bit 63 on), the number-of-days value returned is negative. 


The Run-Time Library provides the date/time utility routines for languages that 
do not have built-in time and date functions, and for particular applications that 
require the time or date in a different format from the one that the language 
supplies. In general, it is simpler to call the Run-Time Library routines for the 
system date and time than to call a system service. 

Condition Values Returned 

SS$_NORMAL Routine successfully completed. 


Example 


PROGRAM DAY(INPUT, OUTPUT); 

{ + } 

{ This is a VAX PASCAL example program showing 
{ the use of LIB$DAY. 

{-} 

VAR 

DAYNUMBER : INTEGER; 

routine LIB$DAY(VAR DAYNUM : INTEGER); 

EXTERN; 

BEGIN 

LIB$DAY(DAYNUMBER); 

WRITELN('The daynumber is DAYNUMBER); 

END. 

A sample of the output generated by this program is shown below. 
The daynumber is 46738 
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LIB$DAY_OF_WEEK—Show Numeric Day of Week 

The Show Numeric Day of Week routine returns the numeric day of the week for 
an input time value. If 0 is the input time value, the current day of the week 
is returned. The days are numbered 1 through 7, with Monday as day 1 and 
Sunday as day 7. 

Format 

UB$DAY_OF_WEEK [user-time,] day-number 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Arguments 

user-time 

OpenVMS usage date_time 
type quadword (unsigned) 

access read only 

mechanism by reference 

Time to be translated to a day of the week, or zero. The optional user-time 
argument is the address of an unsigned quadword containing the value of time. 
Time must be supplied as an absolute system time. To obtain this time value in 
proper quadword format call the system service SYS$BINTIM. 

If time is passed as zero by value, the numeric value for the current day is 
returned. If time is passed as a zero by reference, the number returned 
represents the day of November 17, 1858, rather than the current day. If the 
user-time argument is omitted, it is equivalent to passing a zero by value. 

day-number 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access write only 

mechanism by reference 

Numeric day of week. The day-number argument is the address of a longword 
into which LIB$DAY_OF_WEEK writes the integer value representing the day of 
the week. 

Condition Values Returned 

SS$_NORMAL Routine successfully completed. 


cond_value 
longword (unsigned) 
write only 
by value 
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Example 

PROGRAM DAYOFWEEK(INPUT, OUTPUT); 

{+} 

{ This is an example showing 
{ the use of LIB$DAY_OF_WEEK. 

{-} 

VAR 

OUTDAT : INTEGER; 

routine LIB$DAY_OF_WEEK(TIM : INTEGER; %REF OUTDA : INTEGER); EXTERN; 

BEGIN 

LIB$DAY_OF_WEEK(%IMMED 0, OUTDAT); 

WRITELN(OUTDAT); 

END. 

This Pascal program shows the use of LIB$DAY_OF_WEEK. This example was 
tested on a Monday, and the output generated was “ 1 ”. 
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LIB$DECODE_FAULT—Decode Instruction Stream During Fault 


AXP 


The Decode Instruction Stream During Fault routine is a tool for building 
condition handlers that process instruction fault exceptions. It is called from 
a condition handler. 

This routine is not available to native OpenVMS AXP programs, but is available 
to translated VAX images. ♦ 


Format 


UB$DECODE_FAULT signal-arguments .mechanism-arguments .user-procedure 
[,unspecified-user-argument] [.instruction-definitions] 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Arguments 


signal-arguments 

OpenVMS usage 

type 

access 

mechanism 


vector_longword_unsigned 

unspecified 

read only 

by reference, array reference 


Signal arguments array that was passed from the OpenVMS operating system to 
your condition handler. The signal-arguments argument is the address of the 
signal arguments array. 


mechanism-arguments 

OpenVMS usage vector_longword_unsigned 
type unspecified 

access read only 

mechanism by reference, array reference 

Mechanism arguments array that was passed from OpenVMS to your condition 
handler. The mechanism-arguments argument is the address of the mechanism 
arguments array. 

user-procedure 

OpenVMS usage procedure 
type procedure value 

access call after stack unwind 

mechanism by descriptor, procedure descriptor 

User-supplied action routine that LIB$DECODE_FAULT calls to handle the 
exception. The user-procedure argument is the address of a descriptor pointing 
to your user action routine, user-procedure may be of type “procedure value” 
when called by languages with up-level addressing. If user-procedure is not of 
type “bound routine value,” it is assumed to be the address of an entry mask. 

For further information on the user action routine, see “Call Format for a User 
Action Routine” in the Description section. 
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unspecified-user-argument 

OpenVMS usage user_arg 
type longword (unsigned) 

access read only 

mechanism by value 

Additional information passed from your handler without interpretation to your 
user action routine. The unspecified-user-argument argument contains the 
value of this additional information. This is an optional argument; if omitted, 
zero is used. 

instruction-definitions 

OpenVMS usage vector_byte_unsigned 
type byte (unsigned) 

access read only 

mechanism by reference, array reference 

Array of bytes specifying instruction opcodes and operand definitions which are 
to replace or supplement the standard instruction definitions. The instruction- 
definitions argument is the address of this array. 

If omitted, only the standard instruction definitions are used. If supplied, 
instruction-definitions is searched first, followed by the standard definitions. 

Each instruction definition consists of a series of bytes, the first one or two of 
which is the instruction opcode. If the instruction is a 2-byte opcode, the escape 
byte, which must be hex FD, FE, or FF, is placed in the first of the two bytes. 
Following the opcode may be from 0 to 16 operand definition bytes. These bytes 
indicate the operand’s access type and data type. 

The end of each instruction definition is denoted by a byte containing the value 
LIB$K_DCFOPR_END (zero). The list of instruction definitions is terminated by 
two bytes, each of which contains the value -1, (hexadecimal FF). For further 
information, see “Instruction Operand Definition Codes” in the Description 
section. 


Description 

The Description section of the LIB$DECODE_FAULT routine is divided into five 
parts. 

• Guidelines for Using LIB$DECODE_FAULT 

• Exceptions Recognized by LIB$DECODE_FAULT 

• Instruction Operand Definition Codes 

• Call Format for a User Action Routine 

• Call Format for a Signal Routine 

Guidelines for Using LIB$DECODE_FAULT 

LIB$DECODE_FAULT is a tool for building condition handlers that process 
instruction fault exceptions. Called from a condition handler, LIB$DECODE_ 
FAULT performs the following actions. 

1. Unwinds intermediate stack frames back to that of the exception 

2. Decodes the instruction stream to determine the operation and its operands 
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3. Calls a user-supplied action routine and passes it a consistent and easy-to- 
access description of the instruction’s context 

Your user action routine performs whatever tasks are necessary to handle the 
fault and returns to LIB$DECODE_FAULT. LIB$DECODE_FAULT then restores 
the context as modified by your user action routine and continues execution. 

Your condition handler must first decide whether or not it wishes to handle the 
exception. The signal arguments list contains the exception code and the address 
of the PC that is usually sufficient for this determination. Once LIB$DECODE_ 
FAULT is called, if the exception is a fault LIB$DECODE_FAULT can analyze, 
control does not return to the condition handler. Therefore, your handler must not 
depend on regaining control by a routine return once it has called LIB$DECODE_ 
FAULT. With your user action routine, LIB$DECODE_FAULT makes the original 
fault disappear. 


_ Note _ 

Your user action routine is capable of generating a new exception, 
including one that looks identical to the original exception. Your user 
action routine may also resignal, but if the decision to resignal is made 
inside the user action routine, all post-signal stack frames are lost. 


Once your condition handler has decided that it wants to handle the exception, 

it calls LIB$DECODE_FAULT, passing as arguments the addresses of the signal 

and mechanism argument lists and a descriptor for your user action routine entry 

point. LIB$DECODE_FAULT will then perform the following actions: 

1. Determine if the exception is a fault it understands. If not, it returns SS$_ 
RESIGNAL. 

2. Determine the context in which the exception occurred, including register and 
PSL contents, and save it. 

3. Unwind all stack frames back to that frame in which the exception occurred. 

4. Evaluate each operand’s addressing mode, computing the resulting location 
for the operand. Immediate mode operands are expanded into their full form. 
If an invalid addressing mode is found, an SS$_RADRMOD exception is 
generated. 

5. Unless the original exception was SS$_ACCVIO, test each operand for 
accessibility. If necessary, an access violation is signaled as if the instruction 
had tried to execute normally. See the paragraph following this list for more 
information. 

6. Unless the original exception was SS$_ROPRAND, test each floating-point 
operand that is to be read for a reserved floating operand. If necessary, a 
reserved operand fault is signaled. See the paragraph following this list for 
more information. 

7. Determine the address of the next sequential instruction. 

8. Call your user action routine with arguments as described below. 

9. Upon return from your user action routine, reflect changes to the registers 
and PSL, and continue execution at the instruction address specified by your 
user action routine. Optionally, your user action routine may resignal the 
original exception. 
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Some instructions can generate more than one fault if evaluation of one operand 
causes a fault that occurs before a later operand (which would also cause a fault). 
An example of this is the possibility that a floating-point divide instruction might 
report a divide-by-zero fault upon seeing a zero divisor before noticing that the 
dividend was a reserved operand, or was inaccessible. 

In these cases, operand-specific faults will be signaled immediately by 
LIB$DECODE_FAULT in the expectation that another condition handler (or the 
same one) can repair the situation. This may reorder the sequence of exceptions 
as seen by a program. If the operand exception is corrected, the original exception 
will reoccur, and the proper action will be taken. 

If at all possible, you should attempt to determine if a resignal is necessary inside 
the condition handler that calls LIB$DECODE_FAULT, rather than inside your 
user action routine. The reason for this is that LIB$DECODE_FAULT removes 
all post-signal stack frames before calling your user action routine. 

Your user action routine may fetch and store the operands, registers and PSL as 
is necessary for handling the exception. You should follow the VAX architecture 
rule of reading all input operands in left-to-right order, then writing all output 
operands in left-to-right order, to avoid inconsistent results with overlapping 
operands. This is especially necessary with register operands. 

PSL may be modified in a manner consistent with the VAX architecture. If the 
T-bit in the PSL was set at the beginning of the instruction, LIB$DECODE_ 
FAULT sets the TP bit. To initiate tracing, you must set only the T bit. To 
disable tracing, you must clear both the T and TP bits. See the VAX Architecture 
Reference Manual for more information. 

If the first-part-done (FPD) bit in the PSL was set when the instruction faulted, 
LIB$DECODE_FAULT only advances the PC over the instruction; it does not 
reevaluate the operands and it sets operand-count to zero. It is assumed that if 
FPD is set, the operands are in known locations (typically the registers). 

For the CASEB, CASEW, and CASEL instructions, only the selector, base, 
and limit operands are represented in operand-count and read-operand- 
locations. The element of registers that corresponds to the PC, described in the 
following text as R15, points to the first of the word-length displacements. Your 
user action routine must modify R15 to reflect the location of the next instruction 
to execute. 

The standard instruction definitions used by LIB$DECODE_FAULT specify the 
XFC instruction (which causes an SS$_OPCCUS fault) as having zero operands. 
You may redefine XFC if needed using the instruction-definitions argument to 
LIB$DECODE_FAULT. 

If you do not want instruction execution to resume with the next sequential 
instruction, you must modify R15 appropriately. Your user action routine then 
returns to LIB$DECODE_FAULT which restores the registers and PSL, and 
resumes instruction execution. See also LIB$_RESTART below. 

_ Note _ 

Vector context is not saved or restored. 
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Exceptions Recognized by LIB$DECODE_FAULT 

LIB$DECODE_FAULT recognizes the following VAX faults: 

• SS$_ACCVIO, access violation. 

• SS$_BREAK, breakpoint fault. 

• SS$_FLTDIV_F, floating divide by zero. 

• SS$_FLTOVF_F, floating overflow. 

• SS$_FLTUND_F, floating underflow. 

• SS$_OPCCUS, opcode reserved to customers. 

• SS$_OPCDEC, opcode reserved to Digital. 

• SS$_ROPRAND, reserved operand. 

• SS$_TBIT, T-bit pending trap. This is actually a fault caused by the TP bit 
being set at the beginning of instruction execution. It allows you to interpret 
all instructions by setting the PSL T-bit and allowing each instruction to 
trace-fault. 

All other exceptions, including SS$_COMPAT and SS$_RADRMOD, cause 
LIB$DECODE_FAULT to return immediately with the return status SS$_ 
RESIGNAL. 

SS$_COMPAT is generated by compatibility-mode instructions. LIB$DECODE_ 
FAULT does not handle compatibility-mode instructions. 

SS$_RADRMOD is generated by a reserved addressing-mode fault. 
LIB$DECODE_FAULT assumes that all instructions follow VAX addressing-mode 
specifications. 

Instruction Operand Definition Codes 

Each instruction operand has an access type (read, write, . . . ) and a data type 
(byte, word, . . . ) associated with it. The operand definition codes used in both 
the instruction-definitions argument passed to LIB$DECODE_FAULT and 
in the operand-types argument passed to the user action routine encode the 
access and data types in a byte. The fields and values for operand access and 
data types are described using the symbols in Table LIB-2. These symbols are 
defined in Digital supplied symbol definition libraries as macro or module name 
$LIBDCFDEF. 

Table LIB-2 Symbols for Fields and Values for Operand Access and Data 
Types 

LIB$V_DCFACC The field of the operand description code that describes the 
operand access type (bits 0:2). 

LIB$S_DCFACC The size of the access type field (3 bits). 

(continued on next page) 
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Table LIB-2 (Cont.) 

LIB$M_DCFACC 


LIB$V_DCFTYP 

LIB$S_DCFTYP 

LIB$M_DCFTYP 


Symbols for Fields and Values for Operand Access and 
Data Types 


The mask for the access type field. This is a 3-bit field that 
can contain any binary value from 000 through 111. The 
integer value of these bit settings defines the operand access 
type code for the LIB$M_DCFACC field. Currently, six codes 
are defined. These codes have symbolic names and are 
explained below. It is important to remember that LIB$M_ 
DCFACC is NOT a bit mask. The values 0 through 6 do not 
refer to bits 0 through 6. They represent the binary values 
001 through 110 as contained in the 3-bit field. 

The operand access type codes defined for the LIB$M_ 
DCFACC field are: 


LIB$K_DCFACC_R = 1 
LIB$K_DCFACC_M = 2 
LIB$K_DCFACC_W = 3 
LIB$K_DCFACC_A = 4 

LIB$KJDCFACC_V = 5 


LIB$K_DCFACC_B = 6 


Operand is read-only 
Operand is to be modified 
Operand is write-only 

Operand is an address (must 
not be a register) 

Operand is the base of a bit 
field (same as address except 
that it may be a register) 

Operand is a branch address 

The field of the operand descriptor code that describes the 
operand data type (bits 3:7). 

The size of the operand data type field (5 bits). 


The mask for the operand data type field. This is a 5-bit 
field (bits 3:7) that can contain any binary value from 00000 
through 11111. The integer value of these bit settings defines 
the operand access type code for the LIB$M_DCFACC field. 
Currently, nine codes are defined. These codes have symbolic 
names and are explained below. It is important to remember 
that LIB$M_DCFTYP is NOT a bit mask. The values 0 
through 9 do not refer to bits 0 through 9. They represent 
the binary values 00001 through 01001 as contained in the 
5-bit field. The operand access type codes defined for the 
LIB$V_DCFTYP field are: 


LIB$K_DCFTYP_B = 1 
LIB$K_DCFTYP_W = 2 
LIB$K_DCFTYP_L = 3 
LIB$K_DCFTYP_Q = 4 
LIB$K_DCFTYP_0 = 5 
LIB$K_DCFTYP_F = 6 
LIB$K_DCFTYP_D = 7 
LIB$K_DCFTYP_G = 8 
LIB$K_DCFTYP_H = 9 


Operand is a byte 
Operand is a word 
Operand is a longword 
Operand is a quadword 
Operand is an octaword 
Operand is an F_floating 
Operand is a D_floating 
Operand is a G_floating 
Operand is an H_floating 
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Symbols of the form LIB$K_DCFOPR_xy, where x is the access type and y is the 
data type, are also defined. These combine the notions of access and data type. 
For example, LIB$K_DCFOPR_MF has the following value: 

50 (2+(6*8)) 

It denotes modify access of an F_floating item. For the branch access type, only 
the types BB, BW, and BL are defined; otherwise, all combinations are available. 

Call Format for a User Action Routine 

LIB$DECODE_FAULT calls the user action routine when it finds an exception to 
be handled. Your user action routine handles the exception in any manner that 
you specify and then returns to LIB$DECODE_FAULT. 

action-routine opcode ,instr-PC ,PSL .registers .operand-count 
.operand-types,read-operand-locations 
,write-operand-locations .signal-arguments 
.signal-procedure .context 
,unspecified-user-argument .original-registers 


opcode 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Opcode of the instruction that caused the fault. The opcode argument is the 
address of a longword that contains this opcode. LIB$DECODE_FAULT supplies 
this opcode when it calls the user action routine. 

For 2-byte opcodes, the escape code (for example, hex FD) is in the low-order byte. 
You must use this argument to examine the opcode instead of reading the bytes 
pointed to by instr-PC. This is because if a debugger breakpoint has been set on 
the instruction, only opcode contains the original instruction. 

instr-PC 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Value of the PC for the instruction that caused the fault. The instr-PC argument 
is the address of a longword that contains the PC value. 

Note the difference between this value and the contents of the registers array 
element that corresponds to the PC. R15 of the registers array element contains 
the address of the byte after the instruction that caused the fault. 

PSL 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access modify 

mechanism by reference 

Processor status longword (PSL) at the time of the fault. The PSL argument is 
the address of a longword that contains this PSL. Your user action routine may 
modify this PSL within the restrictions of the VAX architecture. 
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registers 

OpenVMS usage vector_longword_unsigned 
type longword (unsigned) 

access modify 

mechanism by reference, array reference 

Contents of registers RO through R15 (PC) at the time of the fault, but after 
operand addressing-mode processing. This includes any autoincrements and/or 
autodecrements. The registers argument is the address of this 16-longword 
array. Each longword of the registers array contains the contents of one register. 

Your user action routine may modify these values. If it does, the new values will 
be reflected when instruction execution continues. 

To modify vector registers, execute a vector instruction. Executing a vector 
instruction in the handler modifies the state of the vector processor. The state 
of the vector processor is not restored when the handler returns. This has the 
effect of altering the state when the execution continues. 

R15 denotes the 16th longword in the registers array, which corresponds to 
the PC. R15 contains the address of the next byte after the current instruction. 
Unless this value is modified by your user action routine, instruction execution 
will resume at that address. An exception is for the CASEB, CASEW, and CASEL 
instructions; R15 contains the address of the first displacement word. For these 
instructions, your user action routine must modify R15 to point to the next 
instruction to execute. 

Upon instruction completion, registers R0-R15 are restored from this array. 
However, if signal-procedure is used to cause a fault or if instruction restart 
is specified by returning LIB$_RESTART, original-registers is used instead. 

operand-count 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Number of operands in the instruction currently being decoded. The operand- 
count is the address of a longword that contains this number. 

operand-types 

OpenVMS usage vector_longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference, array reference 

Array of longwords, one element for each operand, which contain the type codes 
for the associated operand. The operand-types argument is the address of this 
array. 

The operand type codes are further defined under “Instruction Operand Definition 
Codes,” which appeared above in this Description section. 

read-operand-locations 

OpenVMS usage vector_longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference, array reference 
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Array of longwords, one element for each operand, which contains the addresses 
of the operands to be read. The read-operand-locations argument is the 
address of this array. 

The address given in the array may not be the actual address of the operand if 
the operand is not a memory location. If the operand is a register, the address 
indicates a copy of the register value(s) at the time of operand evaluation. If the 
operand access type is ADDRESS or FIELD, and the operand is not a register, 
the address is the address of the item. If the operand access type is FIELD 
and the operand is a register, the address refers to the appropriate element in 
the registers array. If the operand access type is BRANCH, the address is the 
destination PC of the branch. For WRITE access operands, the address value is 
zero. 

write-operand-locations 

OpenVMS usage vector_longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference, array reference 

Array of longwords, one element for each operand, which contains the addresses 
of operands that are to be written. The write-operand-locations argument is 
the address of this array. If the operand access type is not MODIFY, WRITE, 
ADDRESS, or FIELD, the pointer value is zero. 

signal-arguments 

OpenVMS usage vector_longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference, array reference 

Signal arguments list of the original exception, as passed from OpenVMS to your 
condition handler and then to LIB$DECODE_FAULT. The signal-arguments 
argument is the address of an array of longwords that contains these signal 
arguments. 

signal-procedure 

OpenVMS usage procedure 
type procedure value 

access call without stack unwinding 

mechanism by reference 

Entry mask of a routine that your user action routine must call if it wishes 
to report an exception for the instruction that faulted. The signal-procedure 
argument is the address of this entry mask. 

For further information, see “Call Format for a Signal Routine” in the Description 
section. 

context 

OpenVMS usage context 
type unspecified 

access read only 

mechanism by value 

Context in which the exception occurs, including the register and PSL contents, to 
be used when calling the signal-procedure. The context argument contains the 
value of this context. 
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unspecified-user-argument 


OpenVMS usage 

user_arg 

type 

longword (unsigned) 

access 

read only 

mechanism 

by value 

Optional argument passed to LIB$DECODE_FAULT. If the argument was 
not specified, the value zero is substituted. The unspecified-user-argument 
argument contains the value of this optional argument. 

original-registers 

OpenVMS usage 

vector_longword_unsigned 

type 

longword (unsigned) 

access 

modify 

mechanism 

by reference, array reference 

Array containing the values of registers RO through R15 (PC) at the time of the 
fault, before operand processing. The original-registers argument is the address 
of this 16-longword array. 

If the action routine specifies that the instruction should restart or that a fault 
should be generated, the registers are restored from original-registers. See also 
the description of registers above. 

Condition Values Returned from the User Action Routine The user action 
routine can return the following condition values to LIB$DECODE_FAULT. 

Condition Value 

Description 

SS$_CONTINUE 

If the user action routine returns a value of SS$_ 
CONTINUE, instruction execution will continue as 
specified by the current contents of the registers 
element for the PC. 

ss$_resignal 

If it returns SS$_RESIGNAL, the original exception is 
resignaled, with the only changes reflected being those 
specified by registers elements for RO and R1 (which 
are stored in the mechanism arguments vector), PC, 
and PSL. All other registers are restored from original 
registers. 

LIB$_RESTART 

If the user action routine returns LIB$_RESTART, the 
current instruction is restarted with registers restored 
from original-registers and a PSL from PSL. This 
feature is useful for writing trace handlers. 
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Call Format for a Signal Routine 

Your action routine calls the signal routine using this format: 

signal-procedure fault-flag .context .signal-arguments 

fault-flag 

OpenVMS usage mask_longword 
type longword (unsigned) 

access read only 

mechanism by reference 

Longword flag whose low-order bit determines whether or not the exception is to 
be signaled as a fault or as a trap. The fault-flag argument contains the address 
of this longword. 

If the low-order bit of fault-flag is set to 1, the exception is signaled as a fault. 

If the low-order bit of fault-flag is set to 0, the exception is signaled as a trap; 
the current contents of the registers array are used. In either case, the current 
contents of PSL are used to set the exception PSL. 

context 

OpenVMS usage context 
type unspecified 

access read only 

mechanism by reference 

Context in which the new exception is to occur, as passed to your user action 
routine by LIB$DECODE_FAULT. The context argument is the address of this 
context value. 

signal-arguments 

OpenVMS usage arg_list 

type longword (unsigned) 

access read only 

mechanism by reference, array reference 

Signal arguments to be used. The signal-arguments argument is the address of 
an array of longwords that contains these signal arguments. 

The first longword contains the number of following longwords; the remainder of 
the list contains signal names and arguments. Unlike the signal argument list 
passed to a condition handler, no PC or PSL is present. 

Before the exception is signaled, the stack frames are unwound back to the 
original exception. You should be careful when causing a new signal that a loop 
of faults is not inadvertently generated. For example, the condition handler that 
called LIB$DECODE_FAULT will usually be called for the second signal. If the 
handler does not analyze the second signal as such, it may cycle through the 
identical path as for the first signal. 

To resignal the current exception, have the user action routine return a value of 
SS$_RESIGNAL instead of calling the signal routine (unless you wish previously 
called condition handlers to be called again). 


LIB-93 



LIB$DECODE_FAULT 


Condition Values Returned 

SS$_RESIGNAL Resignal condition to next handler. The exception 

described by signal-arguments was not an 
instruction fault handled by LIB$DECODE_ 
FAULT. If LIB$DECODE_FAULT can process the 
fault, it does not return to its caller. 

Condition Value Signaled 

LIB$_INVARG Invalid argument to Run-Time Library. The 

instruction definition contained more than 16 
operands or an operand definition contained an 
invalid data type or access code. This message 
is signaled after the stack frames have been 
unwound so that it appears to have been signaled 
from a routine that was called by the instruction 
that faulted. 


Example 


c+ 

C Example condition handler and user-action routine using 
C LIB$DECODE_FAULT. This example demonstrates the use of 
C most of the features of LIB$DECODE_FAULT. Its purpose 
C is to handle floating underflow and overflow faults, 

C replacing the result of the instruction with the correctly 
C signed smallest possible value for underflows, or greatest 
C possible value for overflows. 

C 

C For simplicity, faults involving the POLYx instructions are 
C not handled. 

C 

c*** 

C FIXUP_RESULT is the condition handler enabled by the program 
C desiring the fixup of overflows and underflows. 

C*** 

C- 

INTEGERM FUNCTION FIXUP_RESULT(SIGARGS, MECHARGS) 

IMPLICIT NONE 
INCLUDE '($SSDEF)' 

INCLUDE '($LIBDCFDEF)' 

INTEGERM SIGARGS(1:*) 

INTEGER*4 MECHARGS(1s*) 

C+ 

C This is a sample redefinition of MULH3 instruction. 

C- 


! SS$_ symbols 
! LIB$DECODE_FAULT symbols 
I Signal arguments list 
! Mechanism arguments list 


BYTE OPTABLE(8) 
1 
2 

3 

4 

5 


/'FD'X,'65'X, 
LIB$K_DCFOPR_RH, 
LIB$K_DCFOPR_RH, 
LIB$K_DCFOPR_WH, 
LIB$K_DCFOPR_END, 
'FF'X,'FF'X/ 


! MULH3 opcode 
1 Read H__floating 
! Read H_floating 
i Write H_floating 
! End of operands 
! End of instructions 


INTEGER*4 LIB$DECODE_FAULT ! External function 

EXTERNAL FIXUP_ACTION ! Action routine to do the fixup 
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c+ 

C Determine if the exception is one we wish to handle. 

C- 

IF ((SIGARGS(2) .EQ. SS$_FLTOVF_F) .OR. 

1 (SIGARGS(2) .EQ. SS$_FLTUND_F)) THEN 

We think we can handle the fault. Call 
LIB$DECODE_FAULT and pass it the signal arguments and 
the address of our action routine and opcode table. 

FIXUP_RESULT = LIB$DECODE_FAULT (SIGARGS, 

1 MECHARGS, %DESCR(FIXUP_ACTION),, OPTABLE) 

RETURN 
END IF 

C+ 

C We can only get here if we couldn't handle the fault. 

C Resignal the exception. 

C- 

FIXUP_RESULT = SS$_RESIGNAL 

RETURN 

END 

C+ 

C User action routine to handle the fault. 

C- 


c+ 

c 

c 

c 

c- 


INTEGER*4 FUNCTION FIXUP_ACTION 
1 
2 

3 

4 

5 


(OPCODE,INSTR_PC,PSL, 
REGISTERS,OP_COUNT, 
OP_TYPES,READ_OPS, 
WRITE_OPS,SIGARGS, 
SIGNAL_ROUT,CONTEXT, 
USER_ARG,ORIG_REGS) 


IMPLICIT NONE 
INCLUDE '($SSDEF)' 
INCLUDE '($PSLDEF)' 
INCLUDE '($LIBDCFDEF)' 


SS$_ definitions 
PSL$ definitions 
LIB $ DECODE_FAULT 
definitions 


INTEGER*4 OPCODE 
INTEGER*4 INSTR_PC 
INTEGER*4 PSL 


INTEGER*4 REGISTERS(0:15) 
INTEGER*4 OP_COUNT 
INTEGER*4 OP_TYPES(1:*) 
INTEGER*4 READ_OPS(1:*) 
INTEGER*4 WRITE_OPS(1:*) 
INTEGER*4 SIGARGS(1:*) 
INTEGER*4 SIGNAL_ROUT 
INTEGER*4 CONTEXT 
INTEGER*4 USER_ARG 
INTEGER*4 ORIG_REGS(0:15) 


Instruction opcode 
PC of this instruction 
Processor status 
longword 
R0-R15 contents 
Number of operands 
Types of operands 
Addresses of read operands 
Addresses of write operands 
Signal argument list 
Signal routine address 
Signal routine context 
User argument value 
Original registers 
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c+ 

C Declare and initialize table of class codes for each of the 
C "real" opcodes. We'll index into this by the first byte of 
C one-byte opcodes, the second byte of two-byte opcodes. The 
C class codes will be used in a computed GOTO (CASE). The 
C codes are: 

C 0 - Unsupported 

C 1 - ADD 

C 2 - SUB 

C 3 - MUL,DIV 

C 4 - ACB 

C 5 - CVT 

C 6 - EMOD 

C 


The class mainly determines how we compute the 
result, except for ACB. 

sign of the 

BYTE 

INST CLASS TABLE(0:255) 


DATA 

INST CLASS TABLE / 


1 

48*0, 

! 00-2F 

2 

0,0,0,5,0,0,0,0,0,0,0,0,0,0,0,0, 

! 30-3F 

3 

1,1,2,2,3,3,3,3,0,0,0,0,0,0,0,4, 

! 40-4F 

4 

0,0,0,0,6,0,0,0,0,0,0,0,0,0,0,0, 

! 50-5F 

5 

1,1,2,2,3,3,3,3,0,0,0,0,0,0,0,4, 

! 60-6F 

6 

0,0,0,0,6,0,5,0,0,0,0,0,0,0,0,0, 

! 70-7F 

7 

112*0, 

! 80-EF 

8 

0,0,0,0,0,0,5,5,0,0,0,0,0,0,0,0/ 

! F0-FF 


C+ 

C Table of operand sizes in 8-bit bytes, indexed by the 
C datatype code contained in the OP_TYPES array. Only floating 
C types matter. 

C- 


BYTE OP_SIZES(9) 70,0,0,0,0,4,8,8,16/ 


INTEGER*4 LIB$EXTV 
INTEGER*4 RESULTJJEGATIVE 

INTEGER*4 SIGNl,SIGN2,SIGN3 
INTEGER*4 INST_BYTE 
INTEGER*4 INST_CLASS 

INTEGER*4 OP_DTYPE 
INTEGER*4 OP_SIZE 

INTEGER*4 RESULTJDP 

LOGICAL*4 OVERFLOW 
LOGICAL*4 SMALLER 

PARAMETER ESCD = 'OFD'X 

INTEGER*2 SMALL_F(2) 

DATA SMALL_F /'0080'X,0/ 
INTEGER*2 SMALLJD(4) 

DATA SMALL_D /'0080'X,0,0,0/ 
INTEGER* 2 SMALL__G (4 ) 


! External function 
! -1 if result negative, 

! 0 if positive 
! Signs of operands 
! Current opcode byte 
! Class of instruction 
! from table 
l Datatype of operand 
l Size of operand in 
! 8-bit bytes 
! Position of result 
l in WRITE_OPS array 
l TRUE if SS$_ r FLTOVF_F 
i Function which 
! compares operands 
! First byte of G,H instructions 

! Smallest F_floating 
I Smallest D_floating 
! Smallest G_floating 


DATA SMALL_G /'0010'X,0,0,0/ 

INTEGER*2 SMALL_H(8) ! Smallest H_floating 

DATA SMALL_H /'0001'X,0,0,0,0,0,0,0/ 

INTEGER*2 BIGGEST(8) ! Biggest value (all datatypes) 

DATA BIGGEST /'7FFF'X,7*'FFFF'X/ 
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INTEGER*4 SIGNAL_ARRAY(2) ! Array for signalling new 

! exception 
C+ 

C 

C NOTE: Because the operands arrays contain the locations of 
C the operands, rather than the operands themselves, 

C we must call a routine using the %VAL function to 

C "fool" the called routine into considering the 

C contents of an operands array element as the address 

C of an item. This would not be necessary in a 

C language that understood the concept of pointer 

C variables, such as PASCAL. 

C 

C 

C If FPD is set in the PSL, signal SS$_ROPRAND (reserved operand). In 
C reality this shouldn't happen since none of the instructions we 
C handle can set FPD, but do it as an example. 

C- 

IF (BTEST(PSL,PSL$V_FPD)) THEN 
SIGNAL_ARRAY(1) = 1 
SIGNAL_ARRAY (2 ) = SS$_ROPRAND 
CALL SIGNAL_ROUT ( 

1 1, 

2 SIGNAL_ARRAY, 

3 CONTEXT) 

END IF 
C+ 

C Set OVERFLOW according to the exception type. We assume that 
C the only alternatives are SS$_FLTOVF_F and SS$_FLTUND_F. 

C- 

OVERFLOW = (SIGARGS(2) .EQ. SS$_FLTOVF_F) 

C+ 

C Determine the datatype of the instruction by that of its 
C second operand, since that is always the type of the 
C destination. 

C- 

OP_DTYPE = IBITS(OP_TYPES(2),LIB$V_DCFTYP,LIB$S_DCFTYP) 

C+ 

Get the size of the datatype in words. 

OP_SIZE = OP_SIZES (OP_DTYPE) 

C+ 

C Determine the class of instruction and dispatch to the 
C appropriate routine. 

C- 


I Count of signal arguments 
! Error status value 

! Fault flag - signal as fault 
! Signal arguments array 
! Context as passed to us 
! Call will never return 


INST_BYTE = IBITS(OPCODE,0,8) ! Get first byte 

IF (INST_BYTE .EQ. ESCD) INST_BYTE = IBITS(OPCODE,8,8) 

INST_CLASS = INST_CLASS_TABLE(INST_BYTE) 

GO TO (1000,2000,3000,4000,5000,6000),INST_CLASS 

C+ 

C If we get here, the instruction's entry in the 

C INST_CLASS_TABLE is zero. This might happen if the instruction was 
C a POLYx, or was some other unsupported instruction. Resignal the 
C original exception. 

C- 

FIXUP_ACTION = SS$_RESIGNAL ! Resignal condition to next handler 
RETURN ! Return to LIB$DECODE_FAULT 
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c+ 

C 1000 - ADDF2, ADDF3, ADDD2, ADDD3, ADDG2, ADDG3, ADDH2, ADDH3 
C 

C Result's sign is the same as that of the first operand, 

C unless this is an underflow, in which case the magnitudes of 
C the values may change the sign. 

C- 

1000 RESULT_NEGATIVE = LIB$EXTV (15,1,%VAL(READ_OPS(1))) 

IF (.NOT. OVERFLOW) THEN 

IF (SMALLER(OP_SIZE,%VAL(READ_OPS(1)), 

1 %VAL(READ_OPS(2)))) 

2 RESULT_NEGATIVE = .NOT. RESULT_NEGATIVE 
END IF 

GO TO 9000 

C+ 

C 2000 - SUBF2, SUBF3, SUBD2, SUBD3, SUBG2, SUBG3, SUBH2, SUBH3 
C 

C Result's sign is the opposite of that of the first operand, 

C unless this is an underflow, in which case the magnitudes of 
C the values may change the sign. 

C- 

2000 RESULT_NEGATIVE = .NOT. LIB$EXTV (15,1,%VAL(READ_OPS(1))) 
IF (.NOT. OVERFLOW) THEN 

IF (SMALLER(OP_SIZE,%VAL(READ_OPS(l)), 

1 %VAL(READ_OPS(2)))) 

2 RESULT_NEGATIVE = .NOT. RESULT_NEGATIVE 
END IF 

GO TO 9000 

C+ 

C 3000 - MULF2, MULF3, MULD2, MULD3, MULG2, MULG3, MULH2, MULH3, 
C DIVF2, DIVF3, DIVD2, DIVD3, DIVG2, DIVG3, DIVH2, DIVH3, 

C 

C If the signs of the first two operands are the same, then the 
C result's sign is positive, if they are not it is negative. 

C- 

3000 SIGN1 = LIB$EXTV (15,1,%VAL(READ_OPS(1))) 

SIGN2 = LIB$EXTV (15,1, %VAL(READ__OPS (2 ) ) ) 

RESULT_NEGATIVE = SIGN1 .XOR. SIGN2 

GOTO 9000 

C+ 

C 4000 - ACBF, ACBD, ACBG, ACBH 
C 

C The result's sign is the same as that of the second operand 
C (addend), unless this is underflow, in which case the 
C magnitudes of the addend and index may change the sign. 

C We must also determine if the branch is to be taken. 

C- 

4000 SIGN2 = LIB$EXTV (15,1,%VAL(READ_OPS(2))) 

RESULT_NEGATIVE = SIGN2 
IF (.NOT. OVERFLOW) THEN 

IF (SMALLER(OP_SIZE,%VAL(READ_OPS(2)), 

1 %VAL(READ_OPS(3)))) 

2 RESULT_NEGATIVE = .NOT. RESULT_NEGATIVE 
END IF 
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c+ 

C If this is overflow, then the branch is not taken, since the 
C result is always going to be greater or equal in magnitude 
C to the limit, and will be the correct sign. If underflow, 

C the branch is ALMOST always taken. The only case where the 
C branch might not be taken is when the result is exactly 
C equal to the limit. For this example, we are going to ignore 
C this exceptional case. 

C- 

IF (.NOT. OVERFLOW) 

1 REGISTERS(15) = READ_0PS(4) ! Branch destination 
GO TO 9000 

C+ 

C 5000 - CVTDF, CVTGF, CVTHF, CVTHD, CVTHG 
C 

C Result's sign is the same as that of the first operand. 

C- 

5000 RESULT_NEGATIVE = LIB$EXTV ( 15, 1,%VAL(READ_OPS( 1 ))) 

GO TO 9000 

C+ 

C 6000 - EMODF, EMODD, EMODG, EMODH 
C 

C If the signs of the first and third operands are the same, then the 
C result's sign is positive, else it is negative. 

C- 

6000 SIGNl = LIB$EXTV (15,1,%VAL(READ_OPS(1))) 

SIGN2 = LIB$EXTV (15,1,%VAL(READ_OPS(3))) 

RESULTJNEGATIVE = SIGNl .XOR. SIGN2 
GOTO 9000 

C+ 

C All code paths merge here to store the result value. We also 
C set the PSL appropriately. First, determine which operand is 
C the result. 

C- 

9000 RESULT_OP = OP_COUNT 
IF (INST_CLASS .EQ. 4) 

1 RESULT_OP = RESULT_OP - 1 ! ACBx 

C+ 

C Select result based on datatype and exception type. 

C- 

IF (OVERFLOW) THEN 

CALL LIB$MOVC3 (OP_SIZE,BIGGEST,%VAL(WRITE_OPS(RESULT_OP))) 
ELSE 

GO TO (9100,9200,9300,9400), OP_DTYPE-(LIB$K_DCFTYP_F-1) 

C+ 

C Should never get here. Resignal original exception. 

C- 

FIXUP_ACTION = SS$_RESIGNAL 
RETURN 

C+ 

C 9100 - F_floating result 
C- 

9100 CALL LIB$MOVC3 (OP_SIZE,SMALL_F,%VAL(WRITE_OPS(RESULT_OP))) 

GOTO 9500 
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c+ 

C 9200 - D_floating result 
C- 

9200 CALL LIB$MOVC3 (OP_SIZE,SMALL_D,%VAL(WRITE_OPS(RESULT_OP))) 

GOTO 9500 

C+ 

C 9300 - G_floating result 
C- 

9300 CALL LIB$MOVC3 (OP_SIZE,SMALL_G,%VAL(WRITE_OPS(RESULT_OP))) 

GOTO 9500 

C+ 

C 9400 - H_floating result 
C- 

9400 CALL LIB$MOVC3 (OP_SIZE,SMALL_H,%VAL(WRITE_OPS(RESULT_OP))) 

GOTO 9500 

9500 END IF 


C+ 

C Modify the PSL to reflect the stored result. If the result was 
C negative, set the N bit. Clear the V (overflow) and Z (zero) bits. 
C If the instruction was an ACBx, leave the C (carry) bit unchanged, 

C otherwise clear it. 

C- 


IF (RESULT_NEGATIVE) THEN 
PSL = IBSET (PSL,PSL$V_N) 
ELSE 

PSL = IBCLR (PSL,PSL$V_N) 
END IF 

PSL = IBCLR (PSL,PSL$V_V) 

PSL = IBCLR (PSL,PSL$V_Z) 

IF (INST_CLASS .NE. 4) 

1 PSL = IBCLR (PSL,PSL$V_C) 


I Set N bit 

i Clear N bit 

! Clear V bit 
! Clear Z bit 

! Clear C bit if not ACBx 


C+ 

C Set the sign of result. 
C- 


IF (RESULT_NEGATIVE) 

1 CALL LIB$INSV (1,15,1,%VAL(WRITE_OPS(RESULT_OP))) 
C+ 

C Fixup is complete. Return to LIB$DECODE_FAULT. 

C- 


FIXUP_ACTION = SS$_CONTINUE 

RETURN 

END 


C+ 

C Function which compares two floating values. It returns .TRUE, if 
C the first argument is smaller in magnitude than the second. 

C- 

LOGICAL*4 FUNCTION SMALLER(NBYTES,VALl,VAL2) 

INTEGER*4 NBYTES ! Number of bytes in values 

INTEGER*2 VALl(*),VAL2(*) ! Floating values to compare 

INTEGER*4 WORDA,WORDB 

SMALLER = .TRUE. ! Initially return true 

C+ 

C Zero extend to a longword for unsigned compares. 

C Compare first word without sign bit. 

C- 
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WORDA = IBCLR(ZEXT(VALl (1)),15) 

WORDB = IBCLR(ZEXT(VAL2(1)),15) 

IF (WORDA .LT. WORDB) RETURN 

DO 1=2,NBYTES/2 
WORDA = ZEXT(VALl(I)) 

WORDB = ZEXT(VAL2(I)) 

IF (WORDA .LT. WORDB) RETURN 
END DO 

SMALLER = .FALSE. ! VALl not smaller than VAL2 

RETURN 

END 

This FORTRAN example implements a simple recovery scheme for floating 
underflow and overflow faults, replacing the result of the instruction with the 
correctly signed smallest possible value for underflows or largest possible value 
for overflows. 
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LIB$DEC_OVER—Enable or Disable Decimal Overflow Detection 


AXP 


Format 


The Enable or Disable Decimal Overflow Detection routine enables or disables 
decimal overflow detection for the calling routine activation. The previous decimal 
overflow setting is returned. 

This routine is available on OpenVMS AXP systems in translated form and is 
applicable to translated VAX images only. ♦ 


LIB$DEC_OVER new-setting 


Returns 


OpenVMS usage longword_unsigned 
type longword integer (unsigned) 

access write only 

mechanism by value 

The old decimal overflow enable setting (the previous contents of SF$W_ 
PSW[PSW$V_DV] in the caller’s frame). 


Argument 

new-setting 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

New decimal overflow enable setting. The new-setting argument is the address 
of an unsigned longword that contains the new decimal overflow enable setting. 
Bit 0 set to 1 means enable; bit 0 set to 0 means disable. 


Description 

The caller’s stack frame will be modified by this routine. 

A call to LIB$DEC_OVER affects only the current routine activation and does not 
affect any of its callers or any routines that it may call. However, the setting does 
remain in effect for any routines which are subsequently entered through a JSB 
entry point. 


Example 


DECOVF: ROUTINE OPTIONS (MAIN); 

DECLARE LIB$DEC_OVER ENTRY (FIXED BINARY (7)) 


RETURNS (FIXED BINARY (31)); 


/* Address of byte for 
/* enable/disable 
/* setting */ 

/* Old setting */ 


DECLARE DISABLE FIXED BINARY (7) INITIAL (0) STATIC READONLY; 
DECLARE RESULT FIXED BINARY (31); 

DECLARE (A,B) FIXED DECIMAL (4,2); 


ON FIXEDOVERFLOW PUT SKIP LIST ('Overflow'); 
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RESULT = LIB$DEC_OVER (DISABLE); /* Disable recognition of decimal 

/* overflow in this block */ 

A = 99.99; 

B = A + 2; 

PUT SKIP LIST ('In MAIN'); 

BEGIN; 

B = A + 2; 

PUT LIST ('In BEGIN block'); 

CALL Q; 

Q: ROUTINE; 

B = A + 2; 

PUT LIST ('In Q'); 

END Q; 

END /* Begin */; 

END DECOVF; 

This PL/I program shows how to use LIB$DEC_OVER to enable or disable the 
detection of decimal overflow. Note that in PL/I, disabling decimal overflow 
using this routine only causes the condition to be disabled in the current block; 
descendent blocks will enable the condition, unless this routine is called in each 
block. 
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LIB$DELETE_FILE—Delete One or More Files 

The Delete One or More Files routine deletes one or more files. The specification 
of the file(s) to be deleted may include wildcards. 

LIB$DELETE_FILE is similar in function to the DCL command DELETE. 

Format 

LIB$DELETE_FILE filespec [,default-filespec] [,related-filespec] [,user-success-procedure] 

[,user-error-procedure] [,user-confirm-procedure] [,user-specified-argument] 

[,resultant-name] [,file-scan-context] 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Arguments 

filespec 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

String containing the OpenVMS Record Management Services (RMS) file 
specification of the file(s) to be deleted. The filespec argument is the address of a 
descriptor pointing to the file specification. If the specification includes wildcards, 
each file that matches the specification is deleted. The string must not contain 
more than 255 characters. Any string class is supported. 

default-filespec 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Default file specification of the file(s) to be deleted. The default-filespec 
argument is the address of a descriptor pointing to the default file specification. 
This is an optional argument; if omitted, the default is the null string. Any string 
class is supported. 

See the OpenVMS Record Management Services Reference Manual for information 
about default file specifications. 

related-filespec 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Related file specification of the file(s) to be deleted. The related-filespec 
argument is the address of a descriptor pointing to the related file specification. 
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Any string class is supported. This is an optional argument; if omitted, the 
default is the null string. 

Input file parsing is used. See the OpenVMS Record Management Services 
Reference Manual for information on related file specifications and input file 
parsing. 

The related file specification is useful when you are processing lists of file 
specifications. Unspecified portions of the file specification are inherited from the 
last file processed. 

user-success-procedure 

OpenVMS usage procedure 
type procedure value 

access function call (before return) 

mechanism by value 

User-supplied success routine that LIB$DELETE_FILE calls after it successfully 
deletes a file. 

The success routine can be used to display a log of the files that were deleted. For 
more information on the success routine, look under “Call Format for a Success 
Routine” in the Description section. 

user-error-procedure 

OpenVMS usage procedure 
type procedure value 

access function call (before return) 

mechanism by value 

User-supplied error routine that LIB$DELETE_FILE calls when it detects an 
error. 

The error routine returns a success/fail value which LIB$DELETE_FILE uses to 
determine if more files should be processed. For more information on the error 
routine, see “Call Format for an Error Routine” in the Description section. 

user-confirm-procedure 

OpenVMS usage procedure 
type procedure value 

access function call (before return) 

mechanism by value 

User-supplied confirm routine that LIB$DELETE_FILE calls before each file is 
deleted. The value returned by the confirm routine determines whether or not 
the file will be deleted. The confirm routine can be used to select specific files for 
deletion based on criteria such as expiration date, size, and so on. 

For more information about the confirm routine, see “Call Format for a Confirm 
Routine” in the Description section. 

user-specified-argument 

OpenVMS usage user_arg 
type longword (unsigned) 

access read only 

mechanism by value 
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User-supplied argument that LIB$DELETE_FILE passes to the error, success 
and confirm routines each time they are called. Whatever mechanism is also used 
to pass user-specified-argument to LIB$DELETE_FILE is used to pass it to 
the routines. This is an optional argument; if omitted, zero is passed by value. 

resultant-name 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor 

String into which LIB$DELETE_FILE writes the RMS resultant file specification 
of the last file processed. The resultant-name argument is the address of a 
descriptor pointing to the resultant name. 

If present, resultant-name is used to store the file specification passed to the 
user-supplied routines, instead of a default class S, type T string. Therefore, this 
argument should be specified when the user-supplied routines are used and those 
routines require a descriptor type other than class S, type T. Any string class is 
supported. 

If you are specifying one or more of the action routine arguments, be sure that 
the descriptor class used to pass resultant-name is the same as the descriptor 
class required by the action routine. For example, VAX Ada requires a class SB 
descriptor for string arguments to Ada routines, but will use a class A descriptor 
by default when calling external routines. Refer to your language manual to 
determine the proper descriptor class to use. 

file-scan-context 

OpenVMS usage context 
type longword (unsigned) 

access modify 

mechanism by reference 

Context for deleting a list of file specifications. The file-scan-context argument 
is the address of a longword containing the context value. 

You must initialize the file scan context to zero before the first of a series of calls 
to LIB$DELETE_FILE. LIB$FILE_SCAN uses this context to retain the file 
context for multiple input files. You must specify this context only when you are 
dealing with multiple input files, as the DCL command DELETE does. You may 
deallocate the context allocated by LIB$FILE_SCAN by calling LIB$FILE_SCAN_ 
END after all calls to LIB$DELETE_FILE have been completed. 


Description 

This Description section is divided into three parts. 

• Call Format for a Success Routine 

• Call Format for an Error Routine 

• Call Format for a Confirm Routine 
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Call Format for a Success Routine 

The success routine is called only if the user-success-procedure argument was 
specified in the LIB$DELETE_FILE argument list. 

The calling format of a success routine is as follows: 

user-success-procedure filespec [,user-specified-argument] 

filespec 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Record Management Services (RMS) resultant file specification of the file being 
deleted. The filespec argument is the address of a descriptor pointing to the file 
specification. If the resultant-name argument was specified, it is used to pass 
the string to the success routine. Otherwise, a class S, type T string is passed. 
Any string class is supported. 

user-specified-argument 

OpenVMS usage user_arg 
type longword (unsigned) 

access read only 

mechanism unspecified 

Value of user-specified-argument passed by LIB$DELETE_FILE to the success 
routine. The same passing mechanism that was used to pass user-specified- 
argument to LIB$DELETE_FILE is used by LIB$DELETE_FILE to pass 
user-specified-argument to the success routine. This is an optional argument. 

Call Format for an Error Routine 

The error routine is called only if the user-error-procedure argument was 
specified in the LIB$DELETE_FILE argument list. 

The calling format of an error routine is as follows: 

user-error-procedure filespec ,rms-sts ,rms-stv .error-source [,user-specified-argument] 

filespec 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

String containing the RMS resultant file specification of the file being deleted. If 
resultant-name was specified, it is used to pass the string to the error routine. 
Otherwise, a class S, type T string is passed. Any string class is supported. 

rms-sts 

OpenVMS usage cond_value 
type longword (unsigned) 

access read only 

mechanism by reference 

Primary condition code (FAB$L_STS) which describes the error that occurred. 
The rms-sts argument is the address of an unsigned longword that contains the 
primary condition code. 
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rms-stv 

OpenVMS usage cond_value 
type longword (unsigned) 

access read only 

mechanism by reference 

Secondary condition code (FAB$L_STV) which describes the error that occurred. 
The rms-stv argument is the address of an unsigned longword that contains the 
secondary condition code. 

error-source 

OpenVMS usage longword_signed 
type longword integer (signed) 

access read only 

mechanism by reference 

Integer code that indicates the point at which the error was found. The error- 
source argument is the address of a longword integer containing the code of the 
error source. 

Possible values for the error code are as follows: 

0 Error searching for file specification 

1 Error deleting file 

user-specified-argument 

OpenVMS usage user_arg 
type unspecified 

access read only 

mechanism unspecified 

Value passed to LIB$DELETE_FILE that is then passed to user-error- 
procedure using the same passing mechanism that was used to pass it to 
LIB$DELETE_FILE. This is an optional argument. 

If the error routine returns a success status (bit 0 set), then LIB$DELETE_FILE 
will continue processing files. If a failure status (bit 0 clear) is returned, then 
processing will cease immediately and LIB$DELETE_FILE will return with the 
error status. 

If the user-error-procedure argument is not specified, LIB$DELETE_FILE 
will return to its caller the most severe error status encountered while deleting 
the files. If the error routine is called for an error, the success status LIB$_ 
ERRROUCAL is returned. 

The error routine is not called for errors related to string copying. 

Call Format for a Confirm Routine 

The confirm routine is called only if the user-confirm-procedure argument was 
specified in the call to LIB$DELETE_FILE. 

The calling format of the confirm routine is as follows: 

user-confirm-procedure filespec ,fab [,user-specified-argument] 
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filespec 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

RMS resultant file specification of the file to be deleted. The filespec argument 
is the address of a descriptor pointing to the file specification. 

If resultant-name was specified, it is used to pass the string to the confirm 
routine. Otherwise, a class S, type T string is passed. Any string class is 
supported. 


fab 

OpenVMS usage fab 
type unspecified 

access read only 

mechanism by reference 

RMS file access block (FAB) that describes the file being deleted. Your program 
may perform an RMS $OPEN on the FAB to obtain file attributes to determine 
whether the file should be deleted, but it must close the file with $CLOSE before 
returning to LIB$DELETE_FILE. 

user-specified-argument 

OpenVMS usage user_arg 
type unspecified 

access read only 

mechanism unspecified 

The value of the user-specified-argument argument that LIB$DELETE_FILE 
passes to the confirm routine using the same passing mechanism that was used 
to pass it to LIB$DELETE_FILE. This is an optional argument. 

If confirm routine returns a success status (bit 0 set), the file is then deleted; 
otherwise, the file is not deleted. 

Condition Values Returned 


SS$_N ORMAL 
LIB $_E RRROU CAL 

LIB$_INVFILSPE 
LIB$_INVSTRDES 
LIB $_WRONUM ARG 


Routine successfully completed. 

Success, but an error routine was called. A file 
error was encountered but the error routine was 
called to handle the condition. 

Invalid file specification. Filespec or default- 
filespec is longer than 255 characters. 

Invalid string descriptor. The descriptor for a 
string argument was not a valid string descriptor. 

Wrong number of arguments. An incorrect 
number of arguments was passed to 
LIB$DELETE_FILE. 


Any condition value returned by LIB$SCOPY_xxx except those condition values 
specifying truncation errors. 


Any condition value returned by RMS. If user-error-procedure is not specified, 
this is the most severe of the RMS errors encountered while deleting the files. 
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Example 


PROGRAM DELETE_EXAMPLE(INPUT, OUTPUT); 

{ + } 

{ Declare external function LIB$DELETE_FILE. Throughout this 
{ example, the user-arg argument is not used. 

{-} 

FUNCTION LIB$DELETE_FILE( 

FILESPEC: VARYING [A] OF CHAR; 

DEFAULT_FILESPEC: VARYING [B] OF CHAR; 

REL_FILESPEC : VARYING [D] OF CHAR; 

%IMMED [UNBOUND] ROUTINE SUCCESS_ROUTINE 

(FILESPEC : VARYING [A] OF CHAR) := %IMMED 0; 

%IMMED [UNBOUND] FUNCTION ERROR_ROUTINE 

(FILESPEC : VARYING [A] OF CHAR; RMS_STS, RMS_STV : INTEGER) 
: BOOLEAN := %IMMED 0; 

%IMMED [UNBOUND] FUNCTION CONFIRM_ROUTINE 

(FILESPEC: VARYING [A] OF CHAR): BOOLEAN := %IMMED 0; 

VAR USER_ARG : [UNSAFE] INTEGER := %IMMED 0; 

VAR RESULT_NAME : VARYING [C] OF CHAR := %IMMED 0 
) : INTEGER; EXTERN; 


{ + } 

{ Declare a routine which will display the names of the files 
{ as they are deleted. 

{-} 

ROUTINE LOG_ROUTINE(FILESPEC : VARYING [A] OF CHAR); 

BEGIN 

WRITELN('File ', FILESPEC, ' successfully deleted'); 

END; 


{ + } 

{ Declare a routine which will notify the user that an error 
{ occurred. 

{-} 

FUNCTION ERR_ROUTINE(FILESPEC: VARYING [A] OF CHAR; 

RMS_STS, RMS_STV: INTEGER): BOOLEAN; 

BEGIN 

WRITELN('Delete of ', FILESPEC, ' failed ', HEX(RMS_STS)); 
ERR_ROUTINE := TRUE; 

END; 


{ + } 

{ Declare a routine which checks to see if the file should be 
{ deleted. If the filename contains the string 'XYZ', then it is 
{ deleted. 

{-} 

FUNCTION CONFIRM_ROUTINE( FILESPEC: VARYING [A] OF CHAR): BOOLEAN; 
BEGIN 

IF INDEX(FILESPEC, 'XYZ') <> 0 
THEN 

CONFIRM_ROUTINE := TRUE 

ELSE 

CONFIRM_ROUTINE := FALSE; 

END; 


{ + } 

{ The main program begins here. 
{-} 
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VAR 

FILES_TO_DELETE, RESULTANT_NAME : VARYING [255] OF CHAR; 

RET_STATUS : INTEGER; 

BEGIN 

WRITE ('Files to delete: '); 

READLN(FILES_TO_DELETE); 

RET_STATUS := LIB$DELETE_FILE( 

FILES_TO_DELETE, '*;', ", LOG_ROUTINE, ERR_ROUTINE, 

CONFIRM_ROUTINE,,RESULTANT_NAME); 

IF NOT ODD(RET_STATUS) 

THEN 

WRITELNf'Delete failed. The error was ', HEX(RET_STATUS)); 

END. 

This Pascal program prompts the user for file specifications of files to be deleted. 
Of those, it deletes only files which contain the string 'XYZ' somewhere in their 
resultant file specification. The names of deleted files are displayed. 
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LIB$DELETE_LOGICAL—Delete Logical Name 

The Delete Logical Name routine requests the calling process’s Command 
Language Interpreter (CLI) to delete a supervisor-mode process logical name. 
LIB$DELETE_LOGICAL provides the same function as the DCL command 
DEASSIGN. 

Format 

UB$DELETE_LOGICAL logical-name [,table-name] 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Arguments 

logical-name 

OpenVMS usage logical_name 
type character string 

access read only 

mechanism by descriptor 

Logical name to be deleted. The logical-name argument is the address of a 
descriptor pointing to this logical name string. The maximum length of a logical 
name is 255 characters. 

table-name 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Name of the table from which the logical name is to be deleted. The table-name 
argument is the address of a descriptor pointing to this name string. This is an 
optional argument. If omitted, the LNM$PROCESS table is used. 

Description 

LIB$DELETE_LOGICAL requests the calling process’s Command Language 
Interpreter (CLI) to delete a supervisor-mode process logical name. If the 
optional table-name argument is defined, the logical name is deleted from that 
table. Otherwise, the logical name is deleted from the LNM$PROCESS table. 

Unlike the system service $DELLOG and $DELLNM, LIB$DELETE_LOGICAL 
does not require the caller to be executing in supervisor mode to delete a 
supervisor-mode logical name. 

This routine is supported for use with the DCL and MCR Command Language 
Interpreters. 

This routine does not support the DCL DEFINE and DEASSIGN commands’ 
special side-effect of opening and closing a process-permanent file if the logical 
name "SYS$OUTPUT" is specified. 


cond_value 
longword (unsigned) 
write only 
by value 
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If an image is run directly as a subprocess or as a detached process, there is no 
CLI present to perform this function. In that case, the error status LIB$_NOCLI 
is returned. 

See the OpenVMS DCL Dictionary for a description of the DCL command 
DEASSIGN. 


Condition Values Returned 

SS$_ACCVIO 

SS$_IVLOGNAM 

SS$_IVLOGTAB 
SS$_N OLOGNAM 


SS$_NOPRIV 

SS$_NORMAL 

SS$_TOOMANYLNAM 

LIB$_INVSTRDES 

LIB$_NOCLI 


LIB $_UNE C LIE RR 


Access violation. The logical name could not be 
read. 

Invalid logical name. The logical name contained 
illegal characters or more than 255 characters. 

Invalid logical name table 

No logical name match. The logical name was 
not defined as a supervisor-mode process logical 
name. 

No privilege for attempted operation. 

Routine successfully completed. 

Logical name translation exceeded allowed depth. 

Invalid string descriptor. A string descriptor has 
an invalid value in its DSC$B_CLASS field. 

No CLI present to perform function. The calling 
process did not have a CLI to perform the 
function, or the CLI did not support the request 
type. Note that an image run as a subprocess or 
detached process does not have a CLI. 

Unexpected CLI error. The CLI returned an 
error status which was not recognized. This 
error may be caused by use of a nonstandard 
CLI. If this error occurs while using the DCL 
Command Language Interpreter, please report 
the problem to Digital by means of a Software 
Performance Report (SPR). 
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LIB$DELETE_SYMBOL—Delete CLI Symbol 

The Delete CLI Symbol routine requests the calling process’s Command Language 
Interpreter (CLI) to delete an existing CLI symbol. 


Format 


LIB$DELETE_SYMBOL symbol [,table-type-indicator] 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Arguments 


symbol 

OpenVMS usage 

type 

access 

mechanism 


char_string 
character string 
read only 
by descriptor 


Name of the symbol to be deleted by LIB$DELETE_SYMBOL. The symbol 
argument is the address of a descriptor pointing to this symbol string. The 
symbol name is converted to uppercase and trailing blanks are removed before 
use. 


Symbol must begin with a letter, a digit, a dollar sign ($), a hyphen (-), or an 
underscore (_). The maximum length of symbol is 255 characters. 


table-type-indicator 

OpenVMS usage longword_signed 
type longword integer (signed) 

access read only 

mechanism by reference 

Indicator of the table which contains the symbol to be deleted. The table-type- 
indicator argument is the address of a signed longword integer that is this table 
indicator. 

If omitted, the local symbol table is used. The following are possible values for 

the table-type-indicator argument. 


Symbolic Name 

Value 

Table Used 

LIB$K_CLI_LOCAL_SYM 

1 

Local symbol table 

LIB$K_CLI_GLOBAL_SYM 

2 

Global symbol table 
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Description 

LIB$DELETE_SYMBOL is supported for use with the DCL CLI. The error status 
LIB$_NOCLI will be returned if LIB$DELETE_SYMBOL is used with the MCR 
CLI or called from an image run directly as a subprocess or as a detached process. 

LIB$K_CLI_LOCAL_SYM and LIB$K_CLI_GLOBAL_SYM are defined in Digital- 
supplied symbol libraries (macro or module name $LIBCLIDEF) and as global 
symbols. 


Condition Values Returned 

SS$_N ORMAL 
LIB$_FATERRLIB 

LIB$_IN SVIRMEM 

LIB$_INVARG 
LIB$_INVSTRDES 
LIB $_INV S YMN AM 

LIB$_NOCLI 


LIB$_NOSUCHSYM 

LIB$_UNECLIERR 


Routine successfully completed. 

Fatal internal error. An internal consistency 
check has failed. This usually indicates an 
internal error in the Run-Time Library and 
should be reported to Digital. 

Insufficient virtual memory. A call to LIB$GET_ 
VM has failed because your program has 
exceeded the image quota for virtual memory. 

Invalid argument. The value of table-type- 
indicator was invalid. 

Invalid string descriptor. A string descriptor has 
an invalid value in its DSC$B_CLASS field. 
Invalid symbol name. The symbol name 
contained more than 255 characters or did 
not begin with a letter, a dollar sign, or an 
underscore. 

No CLI present to perform the function. The 
calling process did not have a CLI to perform the 
function, or the CLI did not support the request 
type. Note that an image run as a subprocess or 
detached process does not have a CLI. 

No such symbol. The symbol was not defined. 

Unexpected CLI error. The CLI returned an 
error status which was not recognized. This 
error may be caused by use of a nonstandard 
CLI. If this error occurs while using the DCL 
Command Language Interpreter, please report 
the problem to Digital by means of a Software 
Performance Report (SPR). 
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LIB$DELETE_VM_ZONE—Delete Virtual Memory Zone 

The Delete Virtual Memory Zone routine deletes a zone and returns all pages on 
VAX systems or pagelets on AXP systems owned by the zone to the processwide 
page pool. 


Format 

LIB$DELETE_VM_ZONE zone-id 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Argument 


zone-id 

OpenVMS usage 

type 

access 

mechanism 


identifier 

longword (unsigned) 
read only 
by reference 


Zone identifier. The zone-id is the address of a longword that contains the 
identifier of a zone created by a previous call to LIB$CREATE_VM_ZONE or 
LIB$CREATE_USER_VM_ZONE. 


Description 

LIB$DELETE_VM_ZONE deletes a zone and returns all pages on VAX systems 
or pagelets on AXP systems owned by the zone to the processwide pool managed 
by LIB$GET_VM_PAGE. The pages or pagelets are then available for reallocation 
by later calls to LIB$GET_VM or LIB$GET_VM_PAGE. 

It takes less time to free memory in a single operation by calling LIB$DELETE_ 
VM_ZONE than to individually account for and free every block of memory that 
was allocated by calling LIB$GET_VM. 

You must ensure that your program is no longer using any of the memory in the 
zone before you call LIB$DELETE_VM_ZONE. Your program must not do any 
further operations on the zone after you call LIB$DELETE_VM_ZONE. 

If you specified deallocation filling when you created the zone, LIB$DELETE_ 
VM_ZONE will fill all of the allocated blocks that are freed. 

If the zone you are deleting was created using the LIB$CREATE_USER_VM_ 
ZONE routine, then you must have an appropriate action routine for the delete 
operation. That is, in your call to LIB$CREATE_USER_VM_ZONE, you must 
have specified a user-delete-procedure. 
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Condition Values Returned 

SS$_NORMAL Normal successful completion. 

LIB$_BADBLOADR An invalid zone-id argument or a corrupted 

zone. 
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LIB$DIGIT_SEP—Get Digit Separator Symbol 

The Get Digit Separator Symbol routine returns the system’s digit separator 
symbol. 


Format 

LIB$DIGIT_SEP digit-separator-string [.resultant-length] 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 


Arguments 

digit-separator-string 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor 

Digit separator symbol returned by LIB$DIGIT_SEP. The digit-separator-string 
argument is the address of a descriptor pointing to the digit separator. 

resultant-length 

OpenVMS usage word_unsigned 
type word (unsigned) 

access write only 

mechanism by reference 

Number of characters written into digit-separator-string, not counting padding 
in the case of a fixed-length string. The resultant-length argument is the 
address of an unsigned word containing the length of the digit separator symbol. 
If the input string is truncated to the size specified in the digit-separator-string 
descriptor, resultant-length is set to this size. Therefore, resultant-length can 
always be used by the calling program to access a valid substring of digit- 
separator-string. 


Description 

LIB$DIGIT_SEP returns the symbol that is used to separate groups of three 
digits in the integer part of a number, for readability. A common digit separator 
is a comma (,) as in 3,006,854. 

LIB$DIGIT_SEP attempts to translate the logical name SYS$DIGIT_SEP as 
a process, group, or system logical name. If the translation fails, LIB$DIGIT_ 
SEP returns a comma (,), the United States digit separator. If the translation 
succeeds, the text produced is returned. Thus, a system manager can define 
SYS$DIGIT_SEP as a system-wide logical name to provide a default for all users, 
and an individual user with a special need can define SYS$DIGIT_SEP as a 
process logical name to override the default symbol. For example, you may wish 
to use the French digit separator, the period (.). 

BASIC implicitly uses LIB$DIGIT_SEP. 
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Condition Values Returned 

SS$_N ORMAL 
LIB$_STRTRU 

LIB$_FATERRLIB 

LIB$_INSVIRMEM 

LIB$_INVSTRDES 


Routine successfully completed. 

Successfully completed, but the digit separator 
string was truncated. 

Fatal internal error. An internal consistency 
check has failed. This usually indicates an 
internal error in the Run-Time Library and 
should be reported to Digital. 

Insufficient virtual memory. A call to LIB$GET_ 
VM has failed because your program has 
exceeded the image quota for virtual memory. 

Invalid string descriptor. A string descriptor has 
an invalid value in its DSC$B_CLASS field. 


Example 


PROGRAM DIGIT_SEP(INPUT, OUTPUT); 

{ + } 

{ This program uses LIB$DIGIT_SEP to return current 
{ value of SYS$DIGIT_SEP. 

{-} 

routine LIB$DIGIT_SEP(%DESCR DIGIT_SEPSTR : VARYING [A] 

OF CHAR; %REF OUT_LEN : INTEGER); EXTERN; 

VAR 

SEPARATOR : VARYING [256] OF CHAR; 

LENGTH : INTEGER; 

BEGIN 

LIB$DIGIT_SEP(SEPARATOR, LENGTH); 

WRITELN('104 ' ,SEPARATOR,' 567',SEPARATOR,' 934'); 

END. 

This Pascal example demonstrates how to use LIB$DIGIT_SEP. The output 
generated by this program is as follows: 

104,567,934 


LIB-119 



LIB$DISABLE_CTRL 


LIB$DISABLE_CTRL—Disable CLI Interception of Control Characters 

The Disable CLI Interception of Control Characters routine requests the calling 
process’s Command Language Interpreter (CLI) to not intercept the selected 
control characters when they are typed during an interactive terminal session. 
LIB$DISABLE_CTRL provides the same function as the DCL command SET 
NOCONTROL. 

Format 

LIB$DISABLE_CTRL disable-mask [,old-mask] 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Arguments 

disable-mask 

OpenVMS usage mask_longword 
type longword (unsigned) 

access read only 

mechanism by reference 

Bit mask indicating which control characters are not to be intercepted. The 
disable-mask argument is the address of an unsigned longword containing this 
bit mask. 

Each of the 32 bits corresponds to one of the 32 possible control characters. If a 
bit is set, the corresponding control character is no longer intercepted by the CLI 
Currently, only bits 20 and 25, corresponding to Ctrl/t and Ctrl/y, are recognized. 

The following mask is defined in Digital-supplied symbol libraries to specify the 
value of disable-mask. 


Symbol 

Hex Value 

Function 

LIB$M_CLI_CTRLT 

%X'00100000' 

Disables Ctrl/t 

LIB$M_CLI_CTRLY 

%X'02000000' 

Disables Ctrl/y 


If a set bit does not correspond to a character which the CLI can intercept, 
LIB$DISABLE_CTRL returns an error. 


old-mask 

OpenVMS usage mask_longword 
type longword (unsigned) 

access write only 

mechanism by reference 


cond_value 
longword (unsigned) 
write only 
by value 
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Previous bit mask. The old-mask argument is the address of an unsigned 
longword into which LIB$DISABLE_CTRL writes the old bit mask. The old bit 
mask is of the same form as disable-mask, and indicates those control characters 
that were previously enabled. It may therefore be given to LIB$ENABLE_CTRL 
to reinstate the previous condition. 


Description 

The DCL and MCR CLIs can intercept the Ctrl/y control character. The DCL 
CLI can intercept the Ctrl/t character. See the OpenVMS DCL Dictionary for 
information on how the DCL CLI processes control characters. 

LIB$DISABLE_CTRL is supported for use with the DCL and MCR CLIs. If an 
image is run directly as a subprocess or as a detached process, there is no CLI 
present to perform this function. In those cases, LIB$DISABLE_CTRL returns 


the error status LIB$_NOCLI. 

Condition Values Returned 

SS$_NORMAL 

LIB$_INVARG 

LIB$_NOCLI 

LIB$_UNECLIERR 


Routine successfully completed. 

Invalid argument. A bit in disable-mask 
was set which did not correspond to a control 
character supported by the CLI. 

No CLI present. Either the calling process did 
not have a CLI to perform the function, or the 
CLI did not support the request type. Note that 
an image run as a subprocess or detached process 
does not have a CLI. 

Unexpected CLI error. The CLI returned an 
error status which was not recognized. This 
error may be caused by use of a nonstandard 
CLI. If this error occurs while using the DCL or 
MCR CLIs, please report the problem to Digital 
by means of a Software Performance Report 
(SPR). 
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UB$DO_COMMAND—Execute Command 

The Execute Command routine stops program execution and directs the 
Command Language Interpreter to execute a command which you supply as 
the argument. If successful, LIB$DO_COMMAND does not return control to the 
calling program. Instead, LIB$DO_COMMAND begins execution of the specified 
command. 

If you want control to return to the caller, use LIB$SPAWN instead. 


Format 

LIB$DO_COMMAND command-string 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Argument 


command-string 

OpenVMS usage 

type 

access 

mechanism 


char_string 
character string 
read only 
by descriptor 


Text of the command which LIB$DO_COMMAND executes. The command¬ 
string argument is the address of a descriptor pointing to the command text. 
The maximum length of the command is 255 characters. 


Description 

LIB$DO_COMMAND terminates your current image and then executes the 
contents of command-string as a command. The command is parsed using 
normal DCL rules. 

LIB$DO_COMMAND is especially useful when you wish to execute a CLI 
command after your program has finished executing. For example, you could use 
the routine to execute a SUBMIT or PRINT command to handle a file that your 
program has created. 

Because of the following restrictions on LIB$DO_COMMAND, you should be 
careful when you incorporate it in your program. 

• During the call to LIB$DO_COMMAND, the current image exits and control 
cannot return to it. 

• The text of the command is passed to the current Command Language 
Interpreter. Because you can define your own CLI in addition to DCL and 
MCR, you must make sure that the command will be handled by the intended 
CLI. 

• If LIB$DO_COMMAND is called from an image run directly as a subprocess 
or detached process, it will not execute correctly, since no CLI is associated 
with a subprocess. 
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LIB$DO_COMMAND is supported for use with the DCL and MCR CLIs. If an 
image is run directly as a subprocess or as a detached process, there is no CLI 
present to perform this function. In those cases, the error status LIB$_NOCLI is 
returned. Note that the command can execute an indirect file using the at-sign 
(@) feature of DCL. 

Condition Values Returned 


LIB$_INVARG 

LIB$_NOCLI 


LIB$_UNECLIERR 


Invalid argument. Cmd-txt was more than 255 
characters. 

No CLI present. The calling process did not have 
a CLI to perform the function, or the CLI did not 
support the request type. Note that an image 
run as a subprocess or detached process does not 
have a CLI. 

Unexpected CLI error. The CLI returned an 
error status which was not recognized. This 
error may be caused by use of a nonstandard 
CLI. If this error occurs while using the DCL or 
MCR CLIs, please report the problem to Digital 
by means of a Software Performance Report 
(SPR). 


Example 


PROGRAM DO_COMMAND(INPUT, OUTPUT); 

{ + } 

{ This example uses LIB$DO_COMMAND to execute 
{ any DCL command that is entered by the user 
{ at the prompt. 

{-} 

PROCEDURE LIB$DO_COMMAND(CMDTXT : VARYING [A] OF CHAR); 
EXTERN; 


VAR 

COMMAND : VARYING [256] OF CHAR; 

BEGIN 

WRITELNf'ENTER THE COMMAND YOU WANT TO EXECUTE: '); 

READLNfCOMMAND); 

LIB$DO_COMMAND(COMMAND); 

END. 

This Pascal program shows how to call LIB$DO_COMMAND. One example of the 
output of this program is as follows: 

$ RUN DO_COMMAND 

ENTER THE COMMAND YOU WANT TO EXECUTE: SHOW TIME 
30-MAY-1994 14:07:28 
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LIBSEDIV—Extended-Precision Divide 

The Extended-Precision Divide routine performs extended-precision division. 
LIB$EDIV makes the VAX EDIV 1 instruction available as a callable routine. 


Format 


LIB$EDIV longword-integer-divisor .quadword-integer-dividend .longword-integer-quotient .remainder 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 


Arguments 

longword-integer-divisor 

OpenVMS usage longword_signed 
type longword integer (signed) 

access read only 

mechanism by reference 

Divisor. The longword-integer-divisor argument is the address of a signed 
longword integer containing the divisor. 

quadword-integer-dividend 

OpenVMS usage quadword_signed 
type quadword integer (signed) 

access read only 

mechanism by reference 

Dividend. The quadword-integer-dividend argument is the address of a signed 
quadword integer containing the dividend. 

longword-integer-quotient 

OpenVMS usage longword_signed 
type longword integer (signed) 

access write only 

mechanism by reference 

Quotient. The longword-integer-quotient argument is the address of a signed 
longword integer containing the quotient. 

remainder 

OpenVMS usage longword_signed 
type longword integer (signed) 

access write only 

mechanism by reference 

Remainder. The remainder argument is the address of a signed longword 
integer containing the remainder. 


1 On AXP systems, OpenVMS AXP instructions perform the equivalent operation. 
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Condition Values Returned 

SS$_NORMAL 

SS$_INTOVF 

SS$_INTDIV 


Normal successful operation. 

Integer overflow. The quotient is replaced by 
bits 31:0 of the dividend, and the remainder is 
replaced by zero. 

Integer divide by zero. The quotient is replaced 
by bits 31:0 of the dividend, and the remainder is 
replaced by zero. 


Example 


c+ 

C This FORTRAN program demonstrates how to use LIB$EDIV. 

C- 

INTEGER DIVISOR,DIVIDEND)2),QUOTIENT,REMAINDER 
C+ 

C Find the quotient and remainder of 4600387192 divided by 4096. 

C Since 4600387192 is too large to store as a longword, use LIB$EDIV. 

C- 

DIVISOR = 4096 
C+ 

C The dividend must be represented as a quadword. To do this use a vector 
C of length 2. The first element is the low order longword, and the second 
C element is the high order longword. 

C Now, 4600387192 = '00000000112345678'x. So, 

C- 

DIVIDEND(l) = '12345678 ' X 
DIVIDEND)2) = '00000001'X 

C+ 

C Compute the quotient and remainder of 4600387192 divided by 4096. 

C- 

RETURN = LIB$EDIV(DIVISOR,DIVIDEND,QUOTIENT,REMAINDER) 

TYPE *,'The longword integer quotient of 4600387192/4096 is:' 

TYPE *,' ',QUOTIENT 

TYPE *,'The longword integer remainder of 4600387192/4096 is:' 

TYPE *,' ', REMAINDER 

END 

This FORTRAN example demonstrates how to call LIB$EDIV. The output 
generated by this program is as follows: 

The longword integer quotient of 4600387192/4096 is: 

1123141 

The longword integer remainder of 4600387192/4096 is: 

1656 
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LIBSEMODD—Extended Multiply and Integerize Routines for 
D-Floating Point Values 


AXP 


The Extended Multiply and Integerize routine (D-Floating Point Values) allows 
higher-level language users to perform accurate range reduction of D-floating 
arguments. 

D-floating point values are not supported in full precision in native OpenVMS 
AXP programs. They are precise to 56 bits on VAX systems, 53 or 56 bits in 
translated VAX images, and 53 bits in native OpenVMS AXP programs. ♦ 


Format 


LIB$EMODD floating-point-multiplier ,multiplier-extension .floating-point-multiplicand .integer-portion 
.fractional-portion 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 


Arguments 

floating-point-multiplier 

OpenVMS usage floating_point 
type D_floating 

access read only 

mechanism by reference 

The multiplier. The floating-point-multiplier argument is a D-floating number. 

multiplier-extension 

OpenVMS usage byte_unsigned 
type byte (unsigned) 

access read only 

mechanism by reference 

The left-justified multiplier-extension bits. The multiplier-extension argument 
is an unsigned byte. 


floating-point-multiplicand 

OpenVMS usage floating_point 
type D_floating 

access read only 

mechanism by reference 


The multiplicand. The floating-point-multiplicand argument is a D-floating 
number. 


integer-portion 

OpenVMS usage 

type 

access 

mechanism 


longword_signed 
longword integer (signed) 
write only 
by reference 
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The integer portion of the result. The integer-portion argument is the address 
of a signed longword integer containing the integer portion of the result. 

fractional-portion 

OpenVMS usage floating_point 
type D_floating 

access write only 

mechanism by reference 

The fractional portion of the result. The fractional-portion argument is a 
D-floating number. 


Description 

The floating-point multiplier extension operand (second operand) is concatenated 
with the floating-point multiplier (first operand) to gain x additional low-order 
fraction bits. The multiplicand is multiplied by the extended multiplier. After 
multiplication, the integer portion is extracted and a y-bit floating-point number 
is formed from the fractional part of the product by truncating extra bits. 

The multiplication yields a result equivalent to the exact product truncated to a 
fraction field of y bits. With respect to the result as the sum of an integer and 
fraction of the same sign, the integer operand is replaced by the integer part of 
the result and the fraction operand is replaced by the rounded fractional part of 
the result. 

The values of x and y are listed below. 


Routine 

X 

Bits 

y 

LIB$EMODD 

8 

7:0 

64 


Condition Values Returned 

SS$_NORMAL 

SS$_INTOVF 

SS$_FLTUND 

SS$_ROPRAND 


Routine successfully completed. 

Integer overflow. The integer operand is replaced 
by the low-order bits of the true result. Floating 
overflow is indicated by SS$_INTOVF also. 

Floating underflow. The integer and fraction 
operands are replaced by zero. 

Reserved operand. The integer and fraction 
operands are unaffected. 
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LIB$EMODF—Extended Multiply and Integerize Routines for 
F-Floating Point Values 

The Extended Multiply and Integerize routine (F-Floating Point Values) allows 
higher-level language users to perform accurate range reduction of F-floating 
arguments. 


Format 


Returns 


UB$EMODF floating-point-multiplier,multiplier-extension ,floating-point-multiplicand ,integer-portion 
,fractional-portion 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 


Arguments 

floating-point-multiplier 

OpenVMS usage floating_point 
type F_floating 

access read only 

mechanism by reference 

The multiplier. The floating-point-multiplier argument is the address of an 
F-floating number containing the number. 

multiplier-extension 

OpenVMS usage byte_unsigned 
type byte (unsigned) 

access read only 

mechanism by reference 

The left-justified multiplier-extension bits. The multiplier-extension argument 
is the address of an unsigned byte containing these multiplier extension bits. 


floating-point-multiplicand 

OpenVMS usage floating_point 
type F_floating 

access read only 

mechanism by reference 


The multiplicand. The floating-point-multiplicand argument is an F-floating 
number. 


integer-portion 

OpenVMS usage 

type 

access 

mechanism 


longword_signed 
longword (signed) 
write only 
by reference 


The integer portion of the result. The integer-portion argument is the address 
of a signed longword integer containing the integer portion of the result. 
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fractional-portion 

OpenVMS usage floating_point 
type F_floating 

access write only 

mechanism by reference 

The fractional portion of the result. The fractional-portion argument is the 
address of an F-floating number containing the fractional portion of the result. 


Description 

LIB$EMODF allows higher-level language users to perform accurate range 
reduction of F-floating arguments. 

The floating-point multiplier-extension operand (second operand) is 
concatenated with the floating-point-multiplier (first operand) to gain x 
additional low-order fraction bits. The multiplicand is multiplied by the extended 
multiplier. After multiplication, the integer portion is extracted and a y-bit 
floating-point number is formed from the fractional part of the product by 
truncating extra bits. 

The multiplication yields a result equivalent to the exact product truncated to a 
fraction field of y bits. With respect to the result as the sum of an integer and 
fraction of the same sign, the integer operand is replaced by the integer part of 
the result and the fraction operand is replaced by the rounded fractional part of 
the result. 

The values of x and y are listed below. 


Routine 

X 

Bits 

y 

LIB$EMODF 

8 

7:0 

32 


Condition Values Returned 

SS$_N ORMAL 
SS$_INTOVF 

SS$_FLTUND 

SS$_ROPRAND 


Normal successful completion. 

Integer overflow. The integer operand is replaced 
by the low-order bits of the true result. Floating 
overflow is indicated by SS$_INTOVF also. 

Floating underflow. The integer and fraction 
operands are replaced by zero. 

Reserved operand. The integer and fraction 
operands are unaffected. 
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LIBSEMODG—Extended Multiply and Integerize Routines for 
G-Floating Point Values 

The Extended Multiply and Integerize routine (G-Floating Point Values) allows 
higher-level language users to perform accurate range reduction of G-floating 
arguments. 

Format 

UB$EMODG floating-point-multiplier .multiplier-extension .floating-point-multiplicand .integer-portion 
.fractional-portion 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Arguments 

floating-point-multiplier 

OpenVMS usage floating_point 
type G_floating 

access read only 

mechanism by reference 

The multiplier. The floating-point-multiplier argument is a G-floating number. 

multiplier-extension 

OpenVMS usage word_unsigned 
type word (unsigned) 

access read only 

mechanism by reference 

The left-justified multiplier-extension bits. The multiplier-extension argument 
is an unsigned word. 

floating-point-multiplicand 

OpenVMS usage floating_point 
type G_floating 

access read only 

mechanism by reference 

The multiplicand. The floating-point-multiplicand argument is a G-floating 
number. 

integer-portion 

OpenVMS usage longword_signed 
type longword integer (signed) 

access write only 

mechanism by reference 

The integer portion of the result. The integer-portion argument is the address 
of a signed longword integer containing the integer portion of the result. 


cond_value 
longword (unsigned) 
write only 
by value 
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fractional-portion 

OpenVMS usage fioating_point 
type G_floating 

access write only 

mechanism by reference 

The fractional portion of the result. The fractional-portion argument is a 
G-floating number. 


Description 

The floating-point multiplier extension operand (second operand) is concatenated 
with the floating-point multiplier (first operand) to gain x additional low-order 
fraction bits. The multiplicand is multiplied by the extended multiplier. After 
multiplication, the integer portion is extracted and a y-bit floating-point number 
is formed from the fractional part of the product by truncating extra bits. 

The multiplication yields a result equivalent to the exact product truncated to a 
fraction field of y bits. With respect to the result as the sum of an integer and 
fraction of the same sign, the integer operand is replaced by the integer part of 
the result and the fraction operand is replaced by the rounded fractional part of 
the result. 

The values of x and y are listed below. 


Routine 

X 

Bits 

y 

LIB$EMODG 

11 

15:5 

64 


Condition Values Returned 

SS$_N ORMAL 
SS$_INTOVF 

SS$_FLTUND 

SS$_ROPRAND 


Routine successfully completed. 

Integer overflow. The integer operand is replaced 
by the low-order bits of the true result. Floating 
overflow is indicated by SS$_INTOVF also. 

Floating underflow. The integer and fraction 
operands are replaced by zero. 

Reserved operand. The integer and fraction 
operands are unaffected. 
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LIBSEMODH—Extended Multiply and Integerize Routines for 
H-Floating Point Values 


AXP 


Format 


On OpenVMS VAX systems, the Extended Multiply and Integerize routine (H- 
Floating Point Values) allows higher-level language users to perform accurate 
range reduction of H-floating arguments. 

This routine is not available to native OpenVMS AXP programs, but is available 
to translated VAX images. ♦ 


LIBSEMODH floating-point-multiplier .multiplier-extension ,floating-point-multiplicand .integer-portion 
.fractional-portion 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 


Arguments 

floating-point-multiplier 

OpenVMS usage floating_point 
type H_floating 

access read only 

mechanism by reference 

The multiplier. The floating-point-multiplier argument is an H-floating 
number. 


multiplier-extension 

OpenVMS usage word_unsigned 
type word (unsigned) 

access read only 

mechanism by reference 

The left-justified multiplier-extension bits. The multiplier-extension argument 
is an unsigned word. 


floating-point-multiplicand 

OpenVMS usage floating_point 
type H_floating 

access read only 

mechanism by reference 


The multiplicand. The floating-point-multiplicand argument is an H-floating 
number. 


integer-portion 

OpenVMS usage 

type 

access 

mechanism 


longword_signed 
longword integer (signed) 
write only 
by reference 
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The integer portion of the result. The integer-portion argument is the address 
of a signed longword integer containing the integer portion of the result. 

fractional-portion 

OpenVMS usage floating_point 
type H_floating 

access write only 

mechanism by reference 

The fractional portion of the result. The fractional-portion argument is an 
H-floating number. 


Description 

The floating-point multiplier extension operand (second operand) is concatenated 
with the floating-point multiplier (first operand) to gain x additional low-order 
fraction bits. The multiplicand is multiplied by the extended multiplier. After 
multiplication, the integer portion is extracted and a y-bit floating-point number 
is formed from the fractional part of the product by truncating extra bits. 

The multiplication yields a result equivalent to the exact product truncated to a 
fraction field of y bits. With respect to the result as the sum of an integer and 
fraction of the same sign, the integer operand is replaced by the integer part of 
the result and the fraction operand is replaced by the rounded fractional part of 
the result. 

The values of x and y are listed below. 


Routine 

X 

Bits 

y 

LIB$EMODH 

15 

15:1 

128 


Condition Values Returned 

SS$_N ORMAL 
SS$_INTOVF 

SS$_FLTUND 

SS$_ROPRAND 


Routine successfully completed. 

Integer overflow. The integer operand is replaced 
by the low-order bits of the true result. Floating 
overflow is indicated by SS$_INTOVF also. 

Floating underflow. The integer and fraction 
operands are replaced by zero. 

Reserved operand. The integer and fraction 
operands are unaffected. 
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LIBSEMUL—Extended-Precision Multiply 

The Extended-Precision Multiply routine performs extended-precision 
multiplication. LIB$EMUL makes the VAX EMUL 1 instruction available as 
a callable routine. 


Format 

LIB$EMUL longword-integer-multiplier Jongword-integer-multiplicand ,addend product 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 


Arguments 

longword-integer-multiplier 

OpenVMS usage longword_signed 
type longword integer (signed) 

access read only 

mechanism by reference 

Multiplier used by LIB$EMUL in the extended-precision multiplication. The 
longword-integer-multiplier argument is the address of a signed longword 
integer containing the multiplier. 

longword-integer-multiplicand 

OpenVMS usage longword_signed 
type longword integer (signed) 

access read only 

mechanism by reference 

Multiplicand used by LIB$EMUL in the extended-precision multiplication. The 
longword-integer-multiplicand argument is the address of a signed longword 
integer containing the multiplicand. 

addend 

OpenVMS usage longword_signed 
type longword integer (signed) 

access read only 

mechanism by reference 

Addend used by LIB$EMUL in the extended-precision multiplication. The 
addend argument is the address of a signed longword integer containing the 
addend. 

product 

OpenVMS usage quadword_signed 
type quadword integer (signed) 

access write only 

mechanism by reference 


1 On AXP systems, OpenVMS AXP instructions perform the equivalent operation. 
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Product of the extended-precision multiplication. The product argument is the 
address of a signed quadword integer into which LIB$EMUL writes the product. 


Description 

The multiplicand argument is multiplied by the multiplier argument giving a 
double-length result. The addend argument is sign-extended to double-length 
and added to the result. LIB$EMUL then writes the result into the product 
argument. 

Condition Values Returned 

SS$_NORMAL Normal successful completion. 


Example 


INTEGER MULT1,MULT2,ADDEND,PRODUCT(2) 

C+ 

C Find the extended precision multiplication of 268435456 times 4096. 

C That is, find the extended precision product of 2**28 times 2**12. 

C Since 268435456 times 4096 is 2**40, a quadword value is needed for 
C the calculation: use LIB$EMUL. 

C- 

MULT1 = 4096 
MULT2 = 268435456 
APPEND = 0 
C+ 

C Compute 268435456*4096. 

C Note that product will be stored as a quadword. This value will be stored 
C in the 2 dimensional vector PRODUCT. The first element of PRODUCT will 
C contain the low order bits, while the second element will contain the high 
C order bits. 

C- 

RETURN = LIB$EMUL(MULTI,MULT2,APPEND,PRODUCT) 

TYPE *,'PR0DUCT(2) =',PRODUCT(2),' and PRODUCT(l) = \PRODUCT(l) 

TYPE *,' ' 

TYPE *,'Note that 256 and 0 represent the hexadecimal value' 
type *,14H'10000000000'x,', which in turn, represents 2**40.' 

END 

This FORTRAN program demonstrates how to use LIB$EMUL. The output 
generated by this program is as follows: 

PRODUCT(2) = 256 and PRODUCT(l) = 0 

Note that 256 and 0 represent the hexadecimal value ' 10000000000 'x, which in 
turn represents 2 40 . 
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LIB$ENABLE_CTRL—Enable CLI Interception of Control Characters 

The Enable CLI Interception of Control Characters routine requests the calling 
process’s Command Language Interpreter (CLI) to resume interception of the 
selected control characters when they are typed during an interactive terminal 
session. LIB$ENABLE_CTRL provides the same function as the DCL command 
SET CONTROL. 


Format 


Returns 


LIB$ENABLE_CTRL enable-mask [,old-mask] 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Arguments 


enable-mask 

OpenVMS usage 

type 

access 

mechanism 


mask_longword 
longword (unsigned) 
read only 
by reference 


Bit mask indicating for which control characters LIB$ENABLE_CTRL is to 
enable interception. The enable-mask argument is the address of an unsigned 
longword containing this bit mask. Each of the 32 bits corresponds to one of the 
32 possible control characters. If a bit is set, the corresponding control character 
is intercepted by the CLI. Currently, only bits 20 and 25, corresponding to Ctrl/t 
and Ctrl/y, are recognized. 


The following mask is defined in Digital-supplied symbol libraries to specify the 
value of enable-mask. 


Symbol 

Hex Value 

Function 


LIB$M_CLI_CTRLT 

%X’ 00100000' 

Enables Ctrl/t 


LIB$M_CLI_CTRLY 

%X' 02000000' 

Enables Ctrl/t 



If a set bit does not correspond to a character which the CLI can intercept, an 
error is returned. 

old-mask 

OpenVMS usage mask_longword 
type longword (unsigned) 

access write only 

mechanism by reference 

Previous bit mask. The old-mask argument is the address of an unsigned 
longword containing the old bit mask. The old bit mask is of the same form as 

enable-mask. 
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Description 

LIB$ENABLE_CTRL provides the functions of the DCL SET CONTROL 
command. Normally, Ctrl/y interrupts the current command, command procedure, 
or image. After a call to LIB$DISABLE_CTRL, Ctrl/y is treated like Ctrl 
/u followed by a carriage return. LIB$ENABLE_CTRL restores the normal 
operation of Ctrl/y or Ctrl/t. 

Both the DCL and MCR CLIs can intercept control characters. See the OpenVMS 
DCL Dictionary for information on how the CLI processes control characters. 

LIB$ENABLE_CTRL is supported for use with the DCL or MCR CLIs. 

If an image is run directly as a subprocess or as a detached process, there is 
no CLI present to perform this function. In those cases, the error status LIB$_ 
NOCLI is returned. 


Condition Values Returned 

SS$_NORMAL 

LIB$_INVARG 

LIB$_NOCLI 


LIB$_UNECLIERR 


Routine successfully completed. 

Invalid argument. A bit in enable-mask was set 
which did not correspond to a control character 
supported by the CLI. 

No CLI present. The calling process did not have 
a CLI to perform the function, or the CLI did not 
support the request type. Note that an image 
run as a subprocess or detached process does not 
have a CLI. 

Unexpected CLI error. The CLI returned an 
error status which was not recognized. This 
error may be caused by use of a nonstandard 
CLI. If this error occurs while using the DCL or 
MCR CLIs, please report the problem to Digital 
by means of a Software Performance Report 
(SPR). 
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LIBSESTABLISH—Establish a Condition Handler 


AXP 


Format 


The Establish a Condition Handler routine moves the address of a condition 
handling routine (which can be a user-written or a library routine) to longword 0 
of the stack frame of the caller of LIB$ESTABLISH. 

This routine is not available to native OpenVMS AXP programs, but is recognized 
and handled appropriately by most Digital high-level language compilers. ♦ 


LIBSESTABLISH new-handier 


Returns 

OpenVMS usage routine 
type procedure value 

access write only 

mechanism by reference 

Previous contents of SF$A_HANDLER (longword 0) of the caller’s stack frame; 
zero if no handler existed. 

Argument 

new-handier 

OpenVMS usage procedure 
type procedure value 

access read only 

mechanism by value 

Routine to be set up as the condition handler. The new-handier argument is the 
address of the procedure value to this routine. 


Description 

LIB$ESTABLISH moves the address of a condition-handling routine to longword 
0 of the stack frame of the caller of LIB$ESTABLISH. This condition-handling 
routine then becomes the caller’s condition handler. LIB$ESTABLISH returns 
the previous contents of longword 0. This can either be the address of the caller’s 
previous condition handler or zero if no handler existed. 

The new condition handler remains in effect for your routine until you call 
LIB$REVERT or until control returns to the caller of the routine that called 
LIB$ESTABLISH. Once this happens, you must call LIB$ESTABLISH again if 
the same (or a new) condition handler is to be associated with the routine that 
called LIB$ESTABLISH. 

LIB$ESTABLISH modifies the caller’s stack frame. 

LIBSESTABLISH is provided primarily for use with languages without built-in 
error handling facilities. Do not use LIBSESTABLISH with languages that 
provide error handling, such as BASIC, COBOL, Pascal, and PL/I. Use of this 
routine with these languages may adversely affect the behavior of your program. 
The language-support library for these languages depends on predefined 
language-specific handlers. Also, the handler address is used to identify the 
stack frames of routines written in these languages. See the documentation 
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for the language you are using for more information about how that language 
handles errors. 

In VAX MACRO, you merely use the following instruction instead of calling 
LIB$ESTABLISH: 

MOVAB HANDLER, (FP) ; set handler address 

; in current stack frame 

Condition Values Returned 

None. 


Example 


c+ 

C This FORTRAN program demonstrates the 
C use Of LIB$ESTABLISH. 

C 

C This is the main program. 

C- 

EXTERNAL LOG_HANDL 
CHARACTER TIMBUF 

OPEN (UNIT=99, FILE = 'ERRLOG', STATUS = 'NEW') 

CALL LIB$ESTABLISH (LOG_HANDL) 

CALL SYS$BINTIM (TIMBUF, TIMADR) 

C+ 

C The rest of the main program would go here. 

C- 

END 

INTEGERS FUNCTION LOG__HANDL (SIGARGS, MECHARGS) 

INTEGER*4 SIGARGS (*), MECHARGS (5) 

C+ 

C This is the handler to journal any signaled error messages. 

C- 

INCLUDE '($SSDEF)' 

EXTERNAL PUT_LINE 

LOG_HANDL = SS$_RESIGNAL 

CALL SYS$PUTMSG (SIGARGS, PUT_LINE, ) 

RETURN 

END 

C+ 

C This is the action subroutine. 

C- 

LOGICAL*4 FUNCTION PUT_LINE (LINE) 

CHARACTER*(*)LINE 
PUT_LINE = .FALSE. 

100 WRITE (99,200)LINE 

200 FORMAT (A) 

RETURN 

END 

In this FORTRAN example, the function log_handl is the condition handler for 
the program, and thus receives control when an error occurs. 
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LIB$EXTV—Extract a Field and Sign-Extend 

The Extract a Field and Sign-Extend routine returns a sign-extended longword 
field that has been extracted from the specified variable bit field. LIB$EXTV 
makes the VAX EXTV 1 instruction available as a callable routine. 

Format 

LIB$EXTV position ,size ,base-address 

Returns 

OpenVMS usage longword_signed 
type longword integer (signed) 

access write only 

mechanism by value 

Field extracted by LIB$EXTV, sign-extended to a longword. 

Arguments 

position 

OpenVMS usage longword_signed 
type longword integer (signed) 

access read only 

mechanism by reference 

Position (relative to the base address) of the first bit in the field that LIB$EXTV 
extracts. The position argument is the address of a signed longword integer 
containing the position. 

size 

OpenVMS usage byte_unsigned 
type byte (unsigned) 

access read only 

mechanism by reference 

Size of the bit field LIB$EXTV extracts. The size argument is the address of an 
unsigned byte containing the size. The maximum size is 32 bits. 

base-address 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by value 

Base address of the bit field LIB$EXTV extracts from the specified variable bit 
field. The base-address argument is an unsigned longword containing the base 
address. 


1 On AXP systems, OpenVMS AXP instructions perform the equivalent operation. 
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Description 

The variable-length bit field is an OpenVMS data type used to store small 
integers packed together in a larger data structure. It is often used to store 
single flag bits. 

Three scalar attributes define a variable bit field. 

• The base address is the address of a byte in memory that serves as a reference 
point for locating the bit field. 

• The bit position is a signed longword containing the displacement of the least 
significant bit of the field with respect to the bit zero of the base address. 

• The size is a byte integer indicating the size of the bit field in bits (in the 
range 0 < size < 32). That is, a bit field can be no more than one longword in 
length. 

A variable-length bit field has the following format. The area containing asterisks 
indicates the field. 


P+S-1 


★****★★★★**★**** 


:A LIB$EXTV 


-y- 


_A_ 


"V 


S = Size of Field in Bits- 


P = Bit Displacement of Field - 
from Bit Zero of Address A 


ZK-1940-GE 

Bit fields are zero-origin, which means that the routine regards the first bit in the 
field as being the zero position. 


Condition Value Signaled 

SS$_ROPRAND 


Example 


A reserved operand fault occurs if a size greater 
than 32 is specified. 


SIGN_EXTEND: ROUTINE OPTIONS (MAIN); 


DECLARE LIB$EXTV ENTRY 

(FIXED BINARY (31), /* Address of longword containing 

/* beginning bit position */ 

FIXED BINARY (7), /* Address of byte containing size 

/* of field */ 

FIXED BINARY (31)) /* Address of field */ 

RETURNS (FIXED BINARY (31)); /* Return value */ 


DECLARE (VALUE, SMALL_INT) FIXED BINARY (31); 
ON ENDFILE (SYSIN) STOP; 
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DO WHILE ('l'B); /* Loop continuously, until end of file */ 

PUT SKIP(2); 

GET LIST (VALUE) OPTIONS (PROMPT ('Value: ')); 

SMALL_INT = LIB$EXTV ( 0, 4, VALUE); /* Extract and sign-extend 

/* first 4 bits */ 

PUT SKIP LIST (VALUE, SMALL_INT); 

END; 

END SIGN_EXTEND; 

This PL/I program extracts a field and returns it sign-extended into a longword. 
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LIB$EXTZV—Extract a Zero-Extended Field 

The Extract a Zero-Extended Field routine returns a longword zero-extended field 
that has been extracted from the specified variable bit field. LIB$EXTZV makes 
the VAX EXTZV 1 instruction available as a callable routine. 

Format 

LIB$EXTZV position ,size .base-address 

Returns 

OpenVMS usage longword_signed 
type longword integer (signed) 

access write only 

mechanism by value 

Field extracted by LIB$EXTZV, zero-extended to a longword. 

Arguments 

position 

OpenVMS usage longword_signed 
type longword (signed) 

access read only 

mechanism by reference 

Position (relative to the base address) of the first bit in the field LIB$EXTZV 
extracts. The position argument is the address of a signed longword integer 
containing the position. 

size 

OpenVMS usage byte_unsigned 
type byte (unsigned) 

access read only 

mechanism by reference 

Size of the bit field LIB$EXTZV extracts. The size argument is the address of an 
unsigned byte containing the size. The maximum size is 32 bits. 

base-address 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by value 

Base address of the bit field LIB$EXTZV extracts. The base-address argument 
is an unsigned longword containing the base address. 


1 On AXP systems, OpenVMS AXP instructions perform the equivalent operation. 
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Description 

The variable-length bit field is an OpenVMS data type used to store small 
integers packed together in a larger data structure. It is often used to store 
single flag bits. 

Three scalar attributes define a variable bit field. 

• The base address is the address of the byte in memory that serves as a 
reference point for locating the bit field. 

• The bit position is a signed longword containing the displacement of the least 
significant bit of the field with respect to the bit zero of the base address. 

• The size is a byte integer indicating the size of the bit field in bits (in the 
range 0 < size < 32). That is, a bit field can be no more than one longword in 
length. 

A variable-length bit field has the following format. The area containing asterisks 
indicates the field. 


P+S-1 


**************** 


:A LIB$EXTZV 


^ y ^ . y ^ 


S = Size of Field in Bits 


P = Bit Displacement of Field - 
from Bit Zero of Address A 


ZK-1941-GE 

Bit fields are zero-origin fields, which means that the routine regards the first bit 
in the field as being the zero position. 

Condition Value Signaled 

SS$_ROPRAND A reserved operand fault occurs if a size greater 

than 32 is specified. 
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LIB$FFx—Find First Clear or Set Bit 

The Find First Clear or Set Bit routines search the field specified by the start 
position, size, and base for the first clear or set bit. LIB$FFC and LIB$FFS make 
the VAX FFC and VAX FFS 1 instructions available as callable routines. 

Format 

LIB$FFC position ,size ,base ,find-position 
LIB$FFS position ,size ,base ,find-position 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Arguments 

position 

OpenVMS usage longword_signed 
type longword integer (signed) 

access read only 

mechanism by reference 

Starting position, relative to the base address, of the bit field to be searched by 
LIB$FFx. The position argument is the address of a signed longword integer 
containing the starting position. 

size 

OpenVMS usage byte_unsigned 
type byte (unsigned) 

access read only 

mechanism by reference 

Number of bits to be searched by LIB$FFx. The size argument is the address 
of an unsigned byte containing the size of the bit field to be searched. The 
maximum size is 32 bits. 

base 

OpenVMS usage address 
type longword (unsigned) 

access read only 

mechanism by reference 

The base argument is the address of the bit field which LIB$FFx searches. 

find-position 

OpenVMS usage longword_signed 
type longword integer (signed) 

access write only 

mechanism by reference 

1 On OpenVMS AXP systems, OpenVMS AXP instructions perform the equivalent 
operations. 


cond_value 
longword (unsigned) 
write only 
by value 
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Bit position of the first bit in the specified state (clear or set), relative to the 
base address. The find-position argument is the address of a signed longword 
integer into which LIB$FFC writes the position of the first clear bit and into 
which LIB$FFS writes the position of the first set bit. 


Description 

LIB$FFC searches the field specified by the start position, size, and base for the 
first clear bit. LIB$FFS searches the field for the first set bit. 

If a bit in the specified state is found, LIB$FFx writes the position (relative to the 
base) of that bit into find-position and returns a success status. If no bits are 
in the specified state or if size is zero, LIB$FFx returns LIB$_NOTFOU and sets 
find-position to the starting position plus the size. 

LIB$FFx regards the first bit in the field as being the zero position. 


Condition Values Returned 

SS$_N ORMAL 

LIB$_NOTFOU 

Condition Value Signaled 

SS$_ROPRAND 


Routine successfully completed. A bit in the 
specified state was found. 

A bit in the specified state was not found. 


Reserved operand fault. A size greater than 32 
was specified. 
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LIB$FID_TO_NAME—Convert Device and File ID to File Specification 

The Convert Device and File ID to File Specification routine converts a disk 
device name and file identifier to a file specification. 

Format 

UB$FID_TO_NAME device-name ,file-id ,filespec [.filespec-length] [,directory-id] [,acp-status] 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Arguments 

device-name 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Device name to be converted. The device-name argument is the address of a 
descriptor pointing to the device name. Device-name must reference a disk 
device, and must contain 64 characters or less. LIB$FID_TO_NAME obtains 
device-name from the NAM$T_DVI field of a RMS name block. 

file-id 

OpenVMS usage vector_word_unsigned 
type word (unsigned) 

access read only 

mechanism by reference, array reference 

Specifies the file identifier. The file-id argument is the address of an array of 
three words containing the file identification. LIB$FID_TO_NAME obtains file-id 
from the NAM$W_FID field of a RMS name block. The $FIDDEF macro defines 
the structure of file-id. 

filespec 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor 

Receives the file specification. The filespec argument is the address of a 
descriptor pointing to the file specification string. Refer to the Description section 
for more information about the file specification returned. 

filespec-length 

OpenVMS usage word_unsigned 
type word (unsigned) 

access write only 

mechanism by reference 


cond_value 
longword (unsigned) 
write only 
by value 
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Receives the number of characters written into filespec, excluding padding in 
the case of a fixed-length string. The optional filespec-length argument is the 
address of an unsigned word containing the number of characters. 

If the output string is truncated to the number of characters specified in filespec, 
then filespec-length is set to that truncated size. Therefore, you can always use 
filespec-length to access a valid substring of filespec. 

directory-id 

OpenVMS usage vector_word_unsigned 
type word (unsigned) 

access read only 

mechanism by reference, array reference 

Specifies a directory file identifier. The directory-id argument is the address 
of an array of three words containing the directory file identifier. LIB$FID_TO_ 
NAME obtains this array from the NAM$W_DID field of a RMS name block. The 
$FIDDEF macro defines the structure of directory-id. 

acp-status 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access write only 

mechanism by reference 

The status resulting from traversing the backward links. The optional acp- 
status argument is the address of an unsigned longword containing the status. 


Description 


LIB$FID_TO_NAME converts a disk device name and file identifier to a file 
specification by requesting the ACP file specification attribute. 


On OpenVMS VAX systems, if you use the LIB$FID_TO_NAME routine on 
a structure level 1 disk, specify the directory-id argument to ensure proper 
operation of the routine. ♦ 


LIB$FID_TO_NAME uses the directory backpointer stored in the file header. 
With files in SYS$COMMON, the directory structure is duplicated because of 
some SET FILE/ENTERs of directory names. If directory names have been 
renamed or the tree structure modified (which the OpenVMS operating system 
does with the [SYCOMMON] tree), the file specification returned by this routine 
may not be useful. 


LIB$FID_TO_NAME stores the output arguments (filespec, filespec-length, 
and acp-status) only if the routine successfully finishes. 


Condition Values Returned 

LIB $_N ORMAL 

LIB$STRTRU 

LIB$_INVARG 

LIB$_INVFILSPE 


Normal successful completion. 

Output string truncated (qualified success). 

Required argument omitted, or device-name is 
longer than 64 characters. 

Device-name does not reference a disk. 


Any condition value returned by LIB$ANALYZE_SDESC, SYS$ASSIGN, 
SYS$QIO, or SYS$DASSGN. 


LIB-148 



LIB$FILE_SCAN 


LIB$FILE_SCAN—File Scan 

The File Scan routine searches an area, such as a directory, for all files matching 
the file specification given and transfers program execution to the specified user- 
written routine. Wildcards are acceptable. An action routine is called for each 
file and/or error found. LIB$FILE_SCAN allows the search sequence to continue 
even if an error occurs while processing a particular file. 


Format 

LIB$FILE_SCAN fab ,user-success-procedure ,user-error-procedure [,context] 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Arguments 


fab 

OpenVMS usage 

type 

access 

mechanism 


fab 

unspecified 
read only 
by reference 


File Access Block (FAB) referencing a valid NAM block. The fab argument is the 
address of the FAB which contains the address and length of the file specification 
being searched for by LIB$FILE_SCAN. 


user-success-procedure 

OpenVMS usage procedure 
type procedure value 

access function call (before return) 

mechanism by value 

User-supplied success routine that LIB$FILE_SCAN calls when a file is found. 
The success routine is invoked with the FAB address that was passed to 
LIB$FILE_SCAN. The user context may be pased to this routine using the 
FAB$L_CTX field in the FAB. 


user-error-procedure 

OpenVMS usage procedure 

type procedure value 

access function call (before return) 

mechanism by value 

User-supplied error routine that LIB$FILE_SCAN calls when it encounters an 
error. The error routine is called with the FAB argument that was passed to 
LIB$FILE_SCAN. 
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context 

OpenVMS usage context 
type longword (unsigned) 

access modify 

mechanism by reference 

Default file context used in processing file specifications for multiple input files. 
The context argument is the address of a longword, which must be initialized 
to zero by your program before the first call to LIB$FILE_SCAN. After the first 
call, LIB$FILE_SCAN maintains this longword. You must not change the value 
of context in subsequent calls to LIB$FILE_SCAN. 

Name blocks and file specification strings are allocated by LIB$FILE_SCAN, and 
context is used to retain their addresses so they may be deallocated later. If 
the context argument is not passed, unspecified portions of the file specification 
will be inherited from the previous file specification processed, rather than from 
multiple input file specifications. 


Description 

LIB$FILE_SCAN is called with the address of a File Access Block (FAB) and calls 
an action routine for each file found and/or error returned. LIB$FILE_SCAN 
allows the search sequence to continue even if an error occurs while processing a 
particular file. 

If this routine is called once for each file specification argument in a command 
line, portions of the file specifications which are not specified by the user are 
inherited from the last files processed. 

You must call LIB$FILE_SCAN_END before initiating a new sequence of calls to 
LIB$FILE_SCAN. 

Condition Values Returned 

Any condition value returned by the Record Management Service (RMS), Parse. 
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LIB$FILE_SCAN_END—End-of-File Scan 

The End-of-File Scan routine is called after each sequence of calls to LIB$FILE. 
SCAN. LIB$FILE_SCAN_END deallocates any saved Record Management 
Service (RMS) context and/or deallocates the virtual memory that had been 
allocated for holding the related file specification information. 


Format 


Returns 


LIB$FILE_SCAN_END 


OpenVMS usage 

type 

access 

mechanism 


[fab] [.context] 


cond_value 
longword (unsigned) 
write only 
by value 


Arguments 


fab 

OpenVMS usage 

type 

access 

mechanism 


fab 

unspecified 
modify 
by reference 


File access block (FAB) used with LIB$FILE_SCAN. The optional fab argument 
is the address of the FAB that contains the address and length of the file 
specification. 


context 

OpenVMS usage context 
type longword (unsigned) 

access modify 

mechanism by reference 

Temporary default context used in LIB$FILE_SCAN. The optional context 
argument is the address of a longword containing this temporary default context. 


Description 

Your program should call LIB$FILE_SCAN_END after each sequence of calls to 
LIB$FILE_SCAN. The function that LIB$FILE_SCAN_END performs depends 
upon the arguments you specify. If you specify fab, LIB$FILE_SCAN_END 
parses the null string to deallocate any saved RMS context. If you specify 
context, LIB$FILE_SCAN_END deallocates any virtual memory that was 
allocated for holding the related file specification information. If you specify both 
fab and context, LIB$FILE_SCAN_END performs both functions. However, if 
you do not specify either argument, LIB$FILE_SCAN_END does nothing. 
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If LIB$FILE_SCAN is directed to process the specifications for multiple input 
files, LIB$FILE_SCAN_END is used to deallocate those saved file specifications. 
If LIB$FILE_SCAN_END is called by your program after each sequence of calls 
to LIB$FILE_SCAN, it will prevent the defaults from the previous call from 
affecting context value in the next call to LIB$FILE_SCAN. LIB$FILE_SCAN_ 
END does this by replacing the context value passed to it with a temporary 
context value that your program passes to LIB$FILE_SCAN the next time it is 
called. 

Condition Values Returned 

RMS$_NORMAL Normal successful completion. 

RMS$_FAB The fab argument is not the address of a valid 

FAB. 
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LIB$FIND_FILE—Find File 


The Find File routine is called with a wildcard file specification for which it 
searches. LIB$FIND_FILE returns all file specifications that satisfy that wildcard 
file specification. 


Format 


UB$FIND_FILE filespec ,resultant-filespec ,context [,default-filespec] [.related-filespec] [,status-value] 
[.flags] 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Arguments 


filespec 

OpenVMS usage 

type 

access 

mechanism 


char_string 
character string 
read only 
by descriptor 


File specification, which may contain wildcards, that LIB$FIND_FILE uses to 
search for the desired file. The filespec argument is the address of a descriptor 
pointing to the file specification. The maximum length of a file specification is 
255 bytes. 


The file specification used may also contain a search list logical name. If present, 
the search list logical name elements can be used as accumulative to related file 
specifications, so that portions of file specifications not specified by the user will 
be inherited from previous file specifications. 


resultant-filespec 

OpenVMS usage char_string 
type character string 

access modify 

mechanism by descriptor 

Resultant file specification that LIB$FIND_FILE returns when it finds a file 
that matches the specification in the filespec argument. The resultant-filespec 
argument is the address of a descriptor pointing to the resultant file specification. 


context 

OpenVMS usage context 
type longword (unsigned) 

access modify 

mechanism by reference 

A longword integer variable into which the routine stores a context value for 
use by future calls to LIB$FIND_FILE or LIB$FIND_FILE_END. The context 
argument is an unsigned longword integer containing the address of the context. 
This variable must be set to zero before the first call to LIB$FIND_FILE. 
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LIB$FIND_FILE uses this argument to retain the context when processing 
multiple input files. Portions of file specifications that the user does not specify 
are inherited from the last files processed because the file contexts are retained 
in this argument. 

default-filespec 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Default file specification. The default-filespec argument is the address of a 
descriptor pointing to the default file specification. 

related-filespec 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Related file specification containing the context of the last file processed. The 
related-filespec argument is the address of a descriptor pointing to the related 
file specification. 

status-value 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access write only 

mechanism by reference 

Record Management Service (RMS) secondary status value from a failing RMS 
operation. The status-value argument is an unsigned longword containing the 
address of a longword-length buffer to receive the RMS secondary status value 
(usually returned in the file access block field, FAB$L_STV). 

flags 

OpenVMS usage maskjongword 
type longword (unsigned) 

access read only 

mechanism by reference 

User flags. The flags argument is the address of an unsigned longword 
containing the user flags. 

The flag bits and their corresponding symbols are described in the following table. 


Bit Symbol Description 

0 NOWILD If set, LIB$FIND_FILE returns an error if a wildcard 

character is input. 
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Bit Symbol Description 

1 MULTIPLE If set, this performs temporary defaulting for multiple input 
files and the related-filespec argument is ignored. See 
description of context in LIB$FILE_SCAN. Each time 
LIB$FIND_FILE is called with a different file specification, 
the specification from the previous call is automatically 
used as a related file specification. This allows parsing 
of the elements of a search-list logical name such as 
DISK2:[SMITH] FIL1.TYP,FIL*2.TYP, and so on. Use of 
this feature is required to get the desired defaulting with 
search list logical name. LIB$FIND_FILE_END must be 
called between each command line in interactive use or the 
defaults from the previous command line will affect the 
current file specification. 


Description 

LIB$FIND_FILE searches for a certain wildcard file specification and returns all 
file specifications that satisfy that wildcard file specification. 

If you make multiple calls to LIB$FIND_FILE, be aware of the following 
behavior: 

• If, when making the multiple calls, the NO WILD bit is not set and the file 
specification does not contain any wildcard characters, LIB$FIND_FILE 
returns the appropriate file name on the first call and the condition value 
RMS$_NMF on the next call. 

• If you make the multiple calls with the NO WILD bit set and the same 
nonwildcard file specification, LIB$FIND_FILE returns the file name on the 
first call as well as each subsequent call. 

You must call LIB$FIND_FILE_END before initiating a new sequence of calls to 
LIB$FIND_FILE. 

If the error RMS$_CHN is returned, RMS has no more channels to assign. There 
are two possible reasons for this: 

1. You did not call LIB$FIND_FILE_END before initiating a new call with a 
context variable to LIB$FIND_FILE. (This is the most common reason.) 

2. The system parameter CHANNELCNT is too low. 


Condition Values Returned 


RMS$_NORMAL 
LIB $_N O WILD 


RMS$_CHN 

RMS$_NMF 


Routine successfully completed. 

A wildcard character was present in the file 
specification parsed and the wildcard flag bit was 
set to no wildcard. (This is actually the SHR$_ 
NO WILD error message after application of the 
LIB$ facility code.) 

No more channels. 

No more files. 


Any condition value returned by RMS Parse and Search services, LIB$GET_VM, 
LIB$FREE_VM, or LIB$SCOPY_R_DX. 
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LIB$FIND_FILE_END—End of Find File 

The End of Find File routine is called once after each sequence of calls 
to LIB$FIND_FILE. LIB$FIND_FILE_END deallocates any saved Record 
Management Service (RMS) context and deallocates the virtual memory used 
to hold the allocated context block. 


Format 

LIB$FIND_FILE_END context 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Argument 


context 

OpenVMS usage 

type 

access 

mechanism 


context 

longword (unsigned) 
read only 
by reference 


Zero or the address of a FAB/NAM buffer from a previous call to LIB$FIND_ 
FILE. The context argument is the address of a longword that contains this 
context. 


Description 

LIB$FIND_FILE_END should be called by your program after each sequence of 
calls to LIB$FIND_FILE. This will prevent the default values from the previous 
call from affecting the next file specification. 

LIB$FIND_FILE_END deallocates the context used in the last call to LIB$FIND. 
FILE so that the context retained will not be used in subsequent calls to 
LIB$FIND_FILE. If LIB$FIND_FILE was directed to process file specifications 
for multiple input files, the saved file specifications are also deallocated. 

Condition Values Returned 

RMS$_NORMAL Routine successfully completed. 

RMS$_FAB File access block argument is not the address of 

a valid FAB. 
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LIB$FIND_IMAGE_SYMBOL—Find Universal Symbol in Shareable 

Image File 

The Find Universal Symbol in Shareable Image File routine reads universal 
symbols from the shareable image file. This routine then dynamically activates a 
shareable image into the PO address space of a process. 

Format 

LIB$FIND_IMAGE_SYMBOL filename .symbol .symbol-value [.image-name] 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Arguments 

filename 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Name of the file for which LIB$FIND_IMAGE_SYMBOL is searching. The 
filename argument is the address of a descriptor pointing to this file name 
string. This argument may contain only the file name. File type cannot be 
indicated. If any file specification punctuation characters (:, [, <, .) are present, 

the error SS$_IVLOGNAM is returned. 

You can specify a file specification for the image name with the optional 
image-name argument. If you do not specify image-name, a default file 
specification of SYS$SHARE:.EXE is applied to the file name. If the file is not in 
SYS$SHARE:.EXE, a logical name must be used to direct this routine to locate 
the correct file. Only logical names defined in the system logical name table with 
the /EXEC attribute will be considered while the image activator is processing a 
request from an image that was installed with privileges. If the calling image was 
installed with privileges, the image being activated and any shareable images 
or message sections it references must be installed as a known image with the 
INSTALL utility. Running an image to which you have only Execute (not Read) 
access results in the same restrictions on logical names and shareable images as 
does running a privileged image. 

symbol 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Symbol for which LIB$FIND_IMAGE_SYMBOL is searching in the filename file. 
The symbol argument is the address of a descriptor pointing to the symbol name 
string. The symbol name string can be input in uppercase, lowercase, or mixed 
case letters. 


cond_value 
longword (unsigned) 
write only 
by value 
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symbol-value 

OpenVMS usage longword_signed 
type longword (signed) 

access write only 

mechanism by reference 

Symbol value that LIB$FIND_IMAGE_SYMBOL has located. The symbol-value 
argument is the address of a signed longword integer into which LIB$FIND_ 
IMAGE_SYMBOL returns the symbol value. If the symbol is relocatable, the 
starting virtual address of the shareable image in memory will be added to the 
symbol value. 

image-name 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Default file specification applied to the image name. The optional image-name 
argument is a string used as the RMS default file specification when parsing 
filename as the primary filename. If image-name is not supplied, then a 
default file specification of SYS$SHARE:.EXE is applied to the image name. 


Description 

The shareable image that LIB$FIND_IMAGE_SYMBOL activates must have 
been already linked and must be position independent. You must have read 
access to the shareable image file to use this routine. 

LIB$FIND_IMAGE_SYMBOL writes the symbol value that it has located into the 
symbol-value argument. 

After the first call to LIB$FIND_IMAGE_SYMBOL for a particular image, 
successive calls for that image will be processed quickly. The image is activated 
only once and an in-memory database is maintained. There is no way to 
deallocate this database, nor is there any supported method to remove an 
activated image from the address space. All images are activated into PO space. 


AXP 


LIB$FIND_IMAGE_SYMBOL locates the universal symbol in its database 
qualified by the file name exactly as given in the filename argument. Therefore, 
a reference to a lexically different but equivalent file name causes a new copy 
of the same shareable image to be loaded and searched. To avoid this situation, 
always specify the desired file name in the same form. 

To interoperate properly with translated VAX images, LIB$FIND_IMAGE_ 
SYMBOL may modify the name of the file being searched and may retry the 
search if the first search failed. If called from a translated image, LIB$FIND_ 
IMAGE_SYMBOL will append " TV" to the file name before searching. This will 
locate the translated version of the image being searched. If the search fails to 
find the file or the file does not define the symbol, LIB$FIND_IMAGE_SYMBOL 
trys again with the unmodified original file name. This will locate the native 
AXP version of the image. If the second search also fails, an error is returned. 

If LIB$FIND_IMAGE_SYMBOL is called from a native AXP program, the order 
of the searches is reversed. The first search is done with the unmodified original 
file name. If that fails, the second search is done with " TV" appended to the file 
name. If the second search fails, an error is returned. ♦ 
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LIB$FIND_IMAGE_SYMBOL disables AST recognition while it is executing. 

AST recognition is reenabled before returning to the caller only if AST recognition 
was previously enabled. 

LIB$FIND_IMAGE_SYMBOL signals all errors and returns the status in RO. 


Condition Values Returned 

LIB$_BADCCC 

LIB$_EOMERROR 

LIB$_EOMFATAL 

LIB$_EOMWARN 

LIB$_GSDTYP 

LIB$_ILLFMLCNT 

LIB$_ILLMODNAM 

LIB$_ILLPSCLEN 

LIB$_ILLRECLEN 

LIB$_ILLRECLN2 

LIB$_ILLRECTYP 

LIB$_ILLRECTY2 

LIB$_ILLSYMLEN 

LIB$_NOEOM 

LIB$_RECTOOSML 

LIB$_SEQUENCE 

LIB$_SEQUENCE2 

LIB$_STRVL 

Note that all of the above 

error messages indicate a 

format error in the shareable 

image. 

LIB$_INSVIRMEM 

SS$_IVLOGNAM 

Any 
Any 
Any 


Illegal compilation code. 

Compilation errors. 

Fatal compilation errors. 

Compilation warnings. 

Illegal universal symbol directory record type. 
Maximum argument count exceeds maximum for 
routine. 

Illegal module name length. 

Illegal program section length. 

Illegal record length in module. 

Illegal record length. 

Illegal record type in module. 

Illegal record type. 

Illegal symbol length. 

No end of module record contained in the module. 

Record too small; data overflows object record in 
module. 

Illegal record sequence in module. 

Illegal record sequence. 

Illegal object language structure level in module. 


Insufficent virtual memory. 

The filename argument contained more 
than just a file name; a device or directory 
specification was found in the string. 


condition values returned by LIB$INSERT_TREE. 
condition values returned by LIB$LOOKUP_TREE. 
condition values returned by RMS. 
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LIB$FIND_VM_ZONE—Return the Next Valid Zone Identifier 

The Return the Next Valid Zone Identifier routine returns the zone identifier of 
the next valid zone in the heap management database. 

Format 

LIB$FIND_VM_ZONE context ,zone-id 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Arguments 

context 

OpenVMS usage context 
type longword (unsigned) 

access modify 

mechanism by reference 

Context specifier. The context argument is the address of an unsigned longword 
used to keep the scan context for finding the next valid zone. Context must be 0 
to initialize the scan and to start with the first returnable zone identifier. 

zone-id 

OpenVMS usage identifier 
type longword (unsigned) 

access write only 

mechanism by reference 

Zone identifier. The zone-id argument is the address of an unsigned longword 
that receives the zone identifier for the next zone. 

Description 

At each call, LIB$FIND_VM_ZONE scans the heap management zone database 
and returns the zone-id of the next valid zone. (The first and second calls to 
LIB$FIND_VM_ZONE return the zone-id of the default zone and string zone, 
respectively.) This capability allows a program to deal with each VM zone created 
during the invocation, including those created outside of the program. 

The context argument controls the state of the scan. It determines what zone 
to return (the first, the next, and so forth). On the initial call, specified by 
context=0, LIB$VERIFY_VM_ZONE is called to verify the heap management 
zone database. If the database is corrupt, further calls to this routine will produce 
no additional useful output. 

When no more zones can be found, the routine returns the condition value LIB$_ 
NOTFOU. 

If a zone has been corrupted in some major way (for example, if the validity code 
has been changed), then this routine may not be able to locate it in the zone 
database. 
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cond_value 
longword (unsigned) 
write only 
by value 
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Note that ASTs may be disabled while LIB$FIND_VM_ZONE is executing code 
that depends on the stability of the heap management zone database. In general 
it is the caller’s responsibility to ensure that the calling program has exclusive 
access to the zone database while scanning for multiple zones with this routine. 
Results are unpredictable if another thread of control modifies the zone database 
or the associated areas during the scanning. 


Condition Values Returned 

SS$_N ORMAL 

lib$_badzone 

LIB$_NOTFOU 

LIB$_WRONUMARG 


Normal successful completion. 

Invalid zone. 

Zone identifier not found (alternate success 
status). 

Wrong number of arguments. 


Example 


IMPLICIT NONE 

INTEGER*4 status,context,zone_id 
INTEGERM lib$find_vm_zone,lib$show_vm_zone 

context = 0 

status = lib$find_vm_zone (context, zone_id) 

DO WHILE (status) 
print * 

status = lib$show_vm_zone (zone_id, 0) 
status = lib$find_vm_zone (context, zone_id) 

END DO 
END 

Sample output for this FORTRAN program is shown below. 
ZONE ID = 0001B858, Z0NE_NAME = "DEFAULT_ZONE" 
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LIB$FIXUP_FLT—Fix Floating Reserved Operand 


AXP 


Format 


The Fix Floating Reserved Operand routine finds the reserved operand of any 
F-floating, D-floating, G-floating, or H-floating instruction (with some exceptions) 
after a reserved operand fault has been signaled. LIB$FIXUP_FLT changes 
the reserved operand from -0.0 to the value of the new-operand argument, if 
present; or to +0.0 if new-operand is absent. 

This routine is available on OpenVMS AXP systems in translated form and is 
applicable to translated VAX images only. ♦ 


LIB$FIXUP_FLT signal-arguments .mechanism-arguments [,new-operand] 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Arguments 


signal-arguments 

OpenVMS usage 

type 

access 

mechanism 


vector_longword_unsigned 

unspecified 

read only 

by reference, array reference 


Signal argument vector. The signal-arguments argument is the address of an 
array of unsigned longwords containing the signal argument vector. 


mechanism-arguments 

OpenVMS usage vector_longword_unsigned 
type unspecified 

access read only 

mechanism by reference, array reference 

Mechanism argument vector. The mechanism-arguments argument is the 
address of an array of unsigned longwords containing the mechanism argument 
vector. 


new-operand 

OpenVMS usage floating-point 
type F_floating 

access read only 

mechanism by reference 

An F-floating value to replace the reserved operand. The new-operand 
argument is the address of an F-floating number containing the new operand. 
This is an optional argument. If omitted, the default value is +0.0. 
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Description 

LIB$FIXUP_FLT finds the reserved operand of any F-floating, D-floating, G- 
floating, or H-floating instruction (with some exceptions) after a reserved operand 
fault has been signaled. LIB$FIXUP_FLT changes the reserved operand from 
—0.0 to the value of the new-operand argument, if present; or to +0.0 if new- 
operand is absent. LIB$FIXUP_FLT cannot handle the following cases and will 
return a status of SS$_RESIGNAL if any of them occur: 

• The currently active signaled condition is not SS$_ROPRAND. 

• The reserved operand’s data type is not F-floating, D-floating, G-floating, or 
H-floating. 

• The reserved operand is an element in a POLYx coefficient table. 

If the status value returned from LIB$FIXUP_FLT is seen by the condition 
handling facility (as would be the case if LIB$FIXUP_FLT was the handler), any 
success value is equivalent to SS$_CONTINUE, which causes the instruction to 
be restarted. Any failure value is equivalent to SS$_RESIGNAL, which causes 
the condition to be resignaled to the next handler. This resignal status is because 
the condition handler (LIB$FIXUP_FLT) was unable to handle the condition 
correctly. 

LIB$FIXUP_FLT can be enabled directly as a condition handler. The signal- 
arguments and mechanism-arguments arguments are passed to the condition 
handler by OpenVMS exception dispatching. 

Condition Values Returned 


SS$_N ORMAL 

Routine successfully completed. The reserved 
operand was found and has been fixed. 

SS$_ACCVIO 

Access violation. An argument to LIB$FIXUP_ 
FLT or an operand of the faulting instruction 
could not be read or written. 

SS$_RESIGNAL 

The signaled condition was not SS$_ROPRAND, 
or the reserved operand was not a floating-point 
value or was an element in a POLYx table. 

SS$_ROPRAND 

Reserved operand fault. The optional argument 
new-operand was supplied but was itself an 
F-floating reserved operand. 

lib$_badsta 

Bad stack. The stack frame linkage has been 
corrupted since the time of the reserved operand 
exception. 
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LIB$FLT_UNDER—Floating-Point Underflow Detection 


AXP 


The Floating-Point Underflow Detection routine enables or disables floating-point 
underflow detection for the calling routine activation. The previous setting is 
returned as a function value. 

This routine is available on OpenVMS AXP systems in translated form and is 
applicable to translated VAX images only. ♦ 


Format 

LIB$FLT_UNDER new-setting 


Returns 


OpenVMS usage longword_unsigned 
type longword (unsigned) 

access write only 

mechanism by value 

The old floating-point underflow enable setting (the previous contents of the 
SF$W_PSW[PSW$V_FU] in the caller’s frame). 


Argument 

new-setting 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

New floating-point underflow enable setting. The new-setting argument is the 
address of an unsigned byte containing the new setting. Bit 0 set to 1 means 
enable; bit 0 set to 0 means disable. 


Description 

LIB$FLT_UNDER affects only the current routine activation and does not affect 
any of its callers or any routines that it may call. However, the setting does 
remain in effect for any routines entered through a JSB entry point. 

The caller’s stack frame will be modified by this routine. 

Condition Values Returned 

None. 
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Example 


c+ 

C This FORTRAN example program shows 
C the use of LIB$FLT_UNDER. 

C- 

INTEGER*4 NEW_SETTING 
REAL*4 X , Y , Z 

NEW_SETTING = 0 
X = IE-20 

Y = 1E20 

CALL LIB$FLT_UNDER( NEW_SETTING ) 

TYPE *,'First Case: This should not have an underflow exception' 

Z = X / Y 

TYPE *, 'If this lines prints then the underflow exception 
1 was disabled.' 

TYPE * 

NEW_SETTING = 1 
X = IE-20 

Y = 1E20 

CALL LIB$FLT_UNDER( NEW_SETTING ) 

TYPE * , 'Second Case: This should have an underflow exception 
1 and then stop.' 

Z = X / Y 

TYPE * , 'If this line prints, then the underflow exception 
1 was disabled.' 

END 

In this FORTRAN example, floating-point underflow detection is disabled the first 
time X is divided by Y. The second time, underflow detection is enabled, and the 
program stops because of the error generated. 
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LIB$FORMAT_DATE_TIME—Format Date and/or Time 

The Format Date and/or Time routine allows the user to select at run time a 
specific output language and format for a date or time, or both. 

Format 

LIB$FORMAT_DATE_TIME date-string [.date] [,user-context] [,date-length] [,flags] 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Arguments 

date-string 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor 

Receives the requested date or time, or both, that has been formatted for output 
according to the currently selected format and language. The date-string 
argument is the address of a descriptor pointing to this string. 

date 

OpenVMS usage date_time 
type quadword (unsigned) 

access read only 

mechanism by reference 

The date or time, or both, to be formatted for output. The date argument is the 
address of an unsigned quadword that contains the absolute date or time, or both 
to be formatted. If you omit this argument, or if you supply a zero passed by 
value, then the current system time is used. Note that the date argument must 
represent an absolute time, not a delta time. 

user-context 

OpenVMS usage context 
type longword (unsigned) 

access modify 

mechanism by reference 

User context that retains the translation context over multiple calls to this 
routine. The user-context argument is the address of an unsigned longword 
that contains this context. The initial value of the context variable must be zero. 
Thereafter, the user program must not write to the cell. 

The user-context parameter is optional. However, if a context cell is not passed, 
the routine LIB$FORMAT_DATE_TIME may abort if two threads of execution 
attempt to manipulate the context area concurrently. Therefore, when calling 
this routine in situations where reentrancy might occur, such as from AST level, 


cond_value 
longword (unsigned) 
write only 
by value 
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Digital recommends that users specify a different context cell for each calling 
thread. 

date-length 

OpenVMS usage longword_signed 
type longword (signed) 

access write only 

mechanism by reference 

Number of bytes of text written to the date-string argument. The date-length 
argument is the address of a signed longword that receives this string length. 
Note that date-length specifies the number of bytes of text, not the number of 
characters, written to date-string. 

flags 

OpenVMS usage mask_longword 
type longword (unsigned) 

access read only 

mechanism by reference 

Bit mask that allows the user to specify whether the date, time, or both are 
output. The flags argument is the address of an unsigned bit mask containing 
the specified values. Valid values are LIB$M_DATE_FIELDS and LIB$M_TIME_ 
FIELDS. 

Default values are determined as follows: 

• If the flags argument is omitted, LIB$FORMAT_DATE_TIME determines 
which fields to format according to the current definition of LIB$DT_ 
FORMAT. 

• If the flags argument is specified, LIB$FORMAT_DATE_TIME uses the flags 
value to determine which fields to format. That is, the flags argument can be 
used to override the definition of LIB$DT_FORMAT when specifying which 
fields should be formatted for output. If the field specified by flags was not 
assigned a format through the definition of LIB$DT_FORMAT, the standard 
OpenVMS format is used. 


Description 

The LIB$FORMAT_DATE_TIME routine formats an OpenVMS internal format 
date-time quadword into a textual string of some predefined format. The 
language to be used and the format in which to output the information are 
programmable using either of the following methods. 

• The language and format are programmable at compile time through the use 
of the routine LIB$INITJDATE_TIME_CONTEXT. 

• The language and format are determined at run time through the translation 
of the logical names SYS$LANGUAGE and LIB$DT_FORMAT. 

In general, if an application is formatting text for internal storage or 
transmission, the language and format should be specified at compile time. 

If this is the case, use the routine LIB$INIT_DATE_TIME_CONTEXT to specify 
the language and format of your choice. 
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If an application is formatting text for presentation to a user, the logical name 
method of specifying language and format should be used. In this method, the 
user assigns equivalence names to the logical names SYS$LANGUAGE and 
LIB$DT_FORMAT, thereby selecting the language and format of the date and 
time at run time. 

If the logical name method is used, the translations of the logical names 
SYS$LANGUAGE and LIB$DT_FORMAT specify one or more executive mode 
logicals, which in turn must be translated to determine the actual format string. 
These additional logicals supply such things as the names of the days of the week 
and the months in the selected language (determined by SYS$LANGUAGE). 

All of these logicals are predefined, so that a non-privileged user can select any 
one of these languages and formats. A user can create his or her own languages 
and formats; however, the CMEXEC, SYSNAME, and SYSPRV privileges are 
required. 

With the exception of SYS$LANGUAGE and LIB$DT_FORMAT, all logical names 
used by this routine must be defined from the executive mode. 


Condition Values Returned 

SS$_N ORMAL 
LIB$_ENGLUSED 

LIB$_DEFFORUSE 

LIB$_UNRFORCOD 

LIB$_STRTRU 

LIB$_ABSTIMREQ 

LIB$_REENTRANCY 

Any condition values returned 
LIB$ANALYZE_SDESC. 


Normal successful completion. 

English used; unable to determine or use the 
specified language. 

Default format used; unable to determine the 
desired format. 

Unrecognized format code. 

Output string truncated. 

Absolute time required. 

Reentrant invocation with same context variable, 
by SYS$NUMTIM, LIB$GET_VM, and 
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LIB$FORMAT_SOGW_PROT— Format Protection Mask 



On VAX systems, the Format Protection Mask routine translates a protection 
mask into a formatted string. 


Format 


Returns 


LIB$FORMAT_SOGW_PROT protection-mask, [access-names], [ownership-names], 

[ownership-separator], [list-separator], protection-string, [protection-length] 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Arguments 


protection-mask 

OpenVMS usage 

type 

access 

mechanism 


protection 
word (unsigned) 
read only 
by reference 


The protection-mask argument is the address of a word that holds a 16-bit 
protection mask to be translated. 


access-names 

OpenVMS usage access_names 

type array [0..31] of quadword string descriptor 

access read only 

mechanism by reference 

The access-names argument is the address of the access name table for the 
associated object class. For example, it is the value returned by the LIB$GET 
ACCNAM routine in the "accnam" longword. This parameter is optional and 
defaults to the access name table for the FILE object class. 


ownership-names 

OpenVMS usage char_string 

type array [0..3] of quadword string descriptor 

access read only 

mechanism by reference 

The ownership-names argument is the address of a vector of 4 quadword 
descriptors that points to the ownership name. The default value is the full 
ownership category names (System, Owner, Group, World). 

ownership-separator 

OpenVMS usage char_string 
type character-coded text string 

access read only 

mechanism by descriptor 
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The ownership-separator argument is the address of a descriptor that points 
to the ownership separator string. The separator string is inserted after the 
ownership name to introduce a nonempty set of access names. By default, the 
value is ". 

list-separator 

OpenVMS usage char_string 
type character-coded text string 

access read only 

mechanism by descriptor 

The list-separator argument is the address of a descriptor that points to the list 
separator string. The list separator string is inserted between ownership-access 
type pairs. By default, the value is ', '. 

protection-string 

OpenVMS usage char_string 
type character-coded text string 

access write only 

mechanism by descriptor 

The protection-string argument is the address of a character string descriptor 
that receives the output of the routine call, protection-string points to the 
formatted protection string at the end of a call. The protection string has the 
following components repeated for each of: System, Owner, Group, World: 

ownership-name[ownership-separator][access-types][list-separator]. 

An example of a formatted protection string is 

System: RWED, Owner: RWED, Group: RW, World: R 

protection-length 

OpenVMS usage word_signed 
type word (signed) 

access write only 

mechanism by reference 

The protection-length argument is the address of a word that receives the 
length of the string returned in the protection-string argument. 

Description 

LIB$FORMAT_SOGW_PROT translates a 16-bit protection mask into a formatted 
string. This routine works for any protected object class by specifying the correct 
access name table. The address of the access name table can be obtained from 
the LIB$GET_ACCNAM routine. * 

Several formatting options are available. The caller can specify ownership names, 
ownership separators, or list separators. 
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Condition Values Returned 

SS$_NORMAL 

LIB$_INVARG 

STR$_TRU 

LIB$_WRONGNUMARG 


Normal successful completion. 
Required parameter missing. 
String truncation warning. 
Wrong number of arguments. ♦ 
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LIB$FREE_DATE_TIME_CONTEXT—Free the Context Area Used 

When Formatting Dates and 
Times for Input or Output 

The Free the Context Area Used When Formatting Dates and Times for Input or 
Output routine frees the virtual memory associated with the context area used by 
the date/time input and output Formatting Routines. 


Format 

LIB$FREE_DATE_TIME_CONTEXT [user-context] 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Arguments 


user-context 

OpenVMS usage 

type 

access 

mechanism 


context 

longword (unsigned) 

modify 

by reference 


User context that retains the translation context over multiple calls to the date 
/time input and output Formatting Routines. The user-context argument is 
the address of an unsigned longword that contains this context. If the user- 
context argument was not specified in the call to LIB$FORMAT_DATE_TIME, 
LIB$CONVERT_DATE_STRING, or LIB$GET_MAXIMUM_DATE_LENGTH, 
then no argument should be supplied when calling this routine. 


Description 

The LIB$FREE_DATE_TIME_CONTEXT routine frees the virtual memory 
associated with the context area used by the date/time input and output 
formatting routines. A call to this routine is optional, since the same functions 
will be performed at image exit. 

Condition Values Returned 

SS$_NORMAL Normal successful completion. 

Any condition value returned by LIB$FREE_VM. If one of these condition values 
is returned, it indicates either an internal coding error or memory that was 
corrupted by the user’s program. 
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LIB$FREE_EF—Free Event Flag 

The Free Event Flag routine frees a local event flag previously allocated by 
LIB$GET_EF. LIB$FREE_EF is the complement of LIB$GET_EF. 

Format 

UB$FREE_EF event-flag-number 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Argument 

event-flag-number 

OpenVMS usage ef_number 
type longword integer (unsigned) 

access read only 

mechanism by reference 

Event flag number to be deallocated by LIB$FREE_EF. The event-flag-number 
argument is the address of a signed longword integer that contains the event flag 
number, which is the value returned to the user by LIB$GET_EF. 

Description 

When a local event flag allocated by calling LIB$GET_EF is no longer needed, 
LIB$FREE_EF should be called to free the event flag for use by other routines. 

Condition Values Returned 

SS$_NORMAL Routine successfully completed. 

LIB$_EF_ALRFRE Event flag already free. 

LIB$_EF_RESSYS Event flag reserved to system. This error occurs 

if the event flag number is outside the ranges of 
1 to 23 and 32 to 63. 


cond_value 
longword (unsigned) 
write only 
by value 
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LIB$FREE_LUN—Free Logical Unit Number 

The Free Logical Unit Number routine releases a logical unit number allocated 
by LIB$GET_LUN to the pool of available numbers. LIB$FREE_LUN is the 
complement of LIB$GET_LUN. 


Format 

LIB$FREE_LUN logical-unit-number 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Argument 

logical-unit-number 

OpenVMS usage longword_signed 
type longword integer (signed) 

access read only 

mechanism by reference 

Logical unit number to be deallocated. The logical-unit-number argument is 
the address of a signed longword integer that contains this logical unit number, 
which is the value previously returned by LIB$GET_LUN. 


Description 

When a logical unit number allocated by calling LIB$GET_LUN is no longer 
needed, it should be released for use by other routines. 

This routine is useful only in BASIC or FORTRAN programs. 


Condition Values Returned 

SS$_NORMAL 

LIB$_LUNALRFRE 

LIB$_LUNRESSYS 


Routine successfully completed. 

Logical unit number is already free. 

Logical unit number reserved to system. This 
occurs if the specified logical unit number is 
outside the range of 100 to 119. 
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LIB$FREE_TIMER—Free Timer Storage 

The Free Timer Storage routine frees the storage allocated by LIB$INIT_TIMER. 


Format 

LIB$FREE_TIMER handle-address 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Argument 


handle-address 

OpenVMS usage 

type 

access 

mechanism 


address 

longword (unsigned) 

modify 

by reference 


Pointer to a block of storage containing the value returned by a previous call to 
LIB$INIT_TIMER; this is the storage that LIB$FREE_TIMER deallocates. The 
handle-address argument is the address of an unsigned longword containing 
that value. 


Description 

LIB$FREE_TIMER frees a block of storage previously allocated by LIB$INIT_ 
TIMER. LIB$FREE_TIMER assumes that handle-address was returned by a 
previous call to LIB$INIT_TIMER. If the block referred to by handle-address 
was not allocated by LIB$INIT_TIMER, LIB$FREE_TIMER returns an error. If 
the routine completes successfully, LIB$FREE_TIMER sets handle-address to 
zero. 


Condition Values Returned 

SS$_N ORMAL 
LIB$_INVARG 

LIB$_BADBLOADR 


Routine successfully completed. 

Invalid argument; handle-address was not 
supplied or did not point to a timer block. 

Bad block address; LIB$FREE_VM could not 
deallocate the block to which handle-address 
points. 
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LIB$FREE_VM—Free Virtual Memory from Program Region 

The Free Virtual Memory from Program Region routine deallocates an entire 
block of contiguous bytes that were allocated by a previous call to LIB$GET_VM. 
The arguments passed are the same as for LIB$GET_VM. 

Format 

LIB$FREE_VM number-of-bytes ,base-address [,zone-id] 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Arguments 

number-of-bytes 

OpenVMS usage longword_signed 
type longword integer (signed) 

access read only 

mechanism by reference 

Number of contiguous bytes to be deallocated by LIB$FREE_VM. The number- 
of-bytes argument is the address of a signed longword integer that contains this 
number. The value of number-of-bytes must be greater than zero. 

Byte counts are rounded in the same manner as in LIB$GET_VM. 

_ Note _ 

You may omit the number-of-bytes argument if you are using boundary 
tags (LIB $M_VM_B OUNDARY_TAGS). 


base-address 

OpenVMS usage address 
type longword (unsigned) 

access read only 

mechanism by reference 

Address of the first byte to be deallocated by LIB$FREE_VM. The base-address 
argument contains the address of an unsigned longword that is this address. 

The value of base-address must be the address of a block of memory that was 
allocated by a previous call to LIB$GET_VM. 

zone-id 

OpenVMS usage identifier 
type longword (unsigned) 

access read only 

mechanism by reference 


cond_value 
longword (unsigned) 
write only 
by value 
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The zone-id argument is the address of a longword that contains a zone identifier 
created by a previous call to LIB$CREATE_VM_ZONE or LIB$CREATE_USER_ 
VM_ZONE. 

You must specify the same zone-id value as when you called LIB$GET_VM to 
allocate the block. An error status will be returned if you specify an incorrect 
zone-id. The zone-id argument is optional. If zone-id is omitted or if the 
longword contains the value zero, LIB$VM’s default zone is used. 


Description 

LIB$FREE_VM returns the block of memory to a free list associated with the 
zone, so the block is available on a subsequent call to LIB$GET_VM for the zone. 

The base-address argument must contain the address of the first byte of memory 
that was allocated by a previous call to LIB$GET_VM. LIB$FREE_VM rounds up 
the value of number-of-bytes to a multiple of the block size for the zone. 

_ Note _ 

You cannot free part of a block that was allocated by a call to LIB$GET_ 

VM. The whole block must be freed by a single call to LIB$FREE_VM. 

Neither can you combine contiguous blocks of memory that were allocated 
by several calls to LIB$GET_VM into one larger block that is freed by a 
single call to LIB$FREE_VM. 


If you specified deallocation filling when you created the zone, LIB$FREE_VM 
will fill each byte freed. Note that part of a free block is used to store control 
information, so some bytes will not contain the fill value. 

LIB$FREE_VM is fully reentrant, so it can be called by routines executing at 
AST-level or in an Ada multitasking environment. 

If the zone you are freeing was created using the LIB$CREATE_USER_VM_ 
ZONE routine, then you must have an appropriate action routine for the free 
operation. That is, in your call to LIB$CREATE_USER_VM_ZONE, you must 
have specified a user deallocation procedure. 


Condition Values Returned 

SS$_N ORMAL 
LIB$_BADBLOADR 


lib$_badblosiz 

lib$_badtagval 


Routine successfully completed. 

Base-address contained a bad block address. 
Either an address was outside of the area 
allocated by LIB$GET_VM, the contents of 
base-address were not properly aligned, part 
of the space being deallocated was previously 
deallocated, or a zone was found to be corrupt. 

Number-of-bytes is less than or equal to 0, or 
the number-of-bytes argument is incorrect for a 
zone containing fixed size blocks. 

For a zone that uses boundary tags, the tag field 
was corrupted. 
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LIB$FREE_VM_PAGE—Free Virtual Memory Page 

The Free Virtual Memory Page routine deallocates a block of contiguous pages on 
VAX systems or pagelets on AXP systems that were allocated by previous calls to 
LIB$GET_VM_PAGE. 

Format 

LIB$FREE_VM_PAGE number-of-pages ,base-address 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Arguments 

number-of-pages 

OpenVMS usage longword_signed 
type longword integer (signed) 

access read only 

mechanism by reference 

Number of pages on VAX systems or pagelets on AXP systems. The number- 
of-pages argument is the address of a longword integer which specifies the 
number of contiguous pages on VAX systems or pagelets on AXP systems to be 
deallocated. The value of number-of-pages must be greater than zero. 

base-address 

OpenVMS usage address 
type longword (unsigned) 

access read only 

mechanism by reference 

Block address. The base-address argument is the address of a longword which 
contains the address of the first byte of the first VAX page or AXP pagelet to be 
deallocated. 

Description 

LIB$FREE_VM_PAGE deallocates a block of contiguous 512-byte pages starting 
at base-address. Each of the pages or pagelets specified by number-of-pages 
and base-address must have been allocated by previous calls to LIB$GET_ 
VM_PAGE. The pages or pagelets are returned to the processwide pool and are 
available to satisfy subsequent calls to LIB$GET_VM_PAGE. 

You can free a smaller group of pages or pagelets than you allocated. That 
is, if you allocated a group of contiguous pages or pagelets by a single call to 
LIB$GET_VM_PAGE, you can deallocate them in several calls to LIB$FREE_ 
VM_PAGE. You can also combine contiguous groups of pages or pagelets that 
were allocated in several calls to LIB$GET_VM_PAGE into one large group that 
is freed by a single call to LIB$FREE_VM_PAGE. 

LIB$FREE_VM_PAGE is fully reentrant, so it may be called by routines executing 
at AST level or in an Ada multitasking environment. 


cond_value 
longword (unsigned) 
write only 
by value 
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Condition Values Returned 

SS$_N ORMAL 

lib$_badbloadr 


lib$_badblosiz 


Normal successful completion. 

Pages on VAX systems or pagelets on AXP 
systems not allocated by LIB$GET_VM_PAGE, 
the value of base-address is not a page 
boundary, or the pages were previously freed. 
Number-of-pages is less than or equal to zero. 
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LIB$GET_ACCNAM—Get Access Name Table for Protected Object 

Class (by Name) 


On VAX systems, the Get Access Name Table for Protected Object Class (by 
Name) routine returns a pointer to the access name table for a protected object 
class that is specified by name. 


Format 

LIB$GET_ACCNAM [clsnam] , [objnam] ,accnam 

Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Arguments 


clsnam 

OpenVMS usage 

type 

access 

mechanism 


char_string 

character-coded text string 
read only 
by descriptor 


The clsnam argument is the address of a character string descriptor pointing 
to the name of a security object class. This argument is optional and defaults to 


FILE. 


objnam 

OpenVMS usage char_string 
type character-coded text string 

access read only 

mechanism by descriptor 

The objnam argument is the address of a character string descriptor pointing to 
the name of a protected object. This argument is optional. If it is omitted, the 
access name table returned is that used for objects of the class specified by the 
clsnam argument. 

accnam 

OpenVMS usage access_names 
type longword (unsigned) 

access write only 

mechanism by reference 

The accnam argument is the address of a longword into which this routine 
writes the address of the access name table. 
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Description 

LIB$GET_ACCNAM returns the address of the access name table for the specified 
protected object. The format of the table is a vector of 32 quadword string 
descriptors. Each table entry points to the name of an access type. The index 
into the vector is the bit position in an access-desired mask. Undefined access 
types have 0-length names. The table can be used as input to the LIB$PARSE_ 
SOGW_PROT, LIB$FORMAT_SOGW_PROT, LIB$PARSE_ACCESS_CODE, 
$PARSE_ACL, and $FORMAT_ACL routines. 

The semantics of this routine are as follows: 

1. If the clsnam parameter is omitted, it defaults to “FILE”. 

2. If clsnam is not the name of an object class, then the routine returns an 
error status (SS$_NOCLASS) and the value of accnam is undefined. 

3. If the objnam parameter is omitted, then accnam points to the table 
corresponding to clsnam and the routine returns a success status (SS$_ 
NORMAL). The table returned is the table of access names for a new object of 
class clsnam. 

4. Otherwise, if clsnam and objnam do in fact name a protected object, then 
accnam points to the table corresponding to the protected object class and 
the routine returns a success status (SS$_NORMAL) 

5. else if clsnam and objnam do not name a protected object, then the routine 
returns an error status (the exact status value depends on the security class) 
and the value of accnam is undefined. 


Condition Values Returned 


SS$_NORMAL 
SS$_N OCLASS 
LIB$_WRONUMARG 
LIB$_INVARG 


Normal successful completion. 

No matching object class was found. 
Wrong number of arguments, 
accnam parameter was omitted. 


In addition, any completion status may be returned from $GET_SECURITY. ♦ 
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LIB$GET_ACCNAM_BY_CONTEXT—Get Access Name Table for 

Protected Object Class (by 
Context) 


On VAX systems, the Get Access Name Table for Protected Object Class (by 
Context) routine returns a pointer to the access name table for a protected object 
class that is specified by a context longword returned from $GET_SECURITY or 
$SET_SECURITY. 


Format 


Returns 


LIB$GET_ACCNAM_BY_CONTEXT contxt ,accnam 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Arguments 


contxt 

OpenVMS usage 

type 

access 

mechanism 


context 

longword (unsigned) 
read only 
by reference 


The contxt argument is the address of a non-zero longword context value 
returned by $GET_SECURITY or $SET_SECURITY. 


accnam 

OpenVMS usage access_names 
type longword (unsigned) 

access write only 

mechanism by reference 

The accnam argument is the address of a longword into which this routine 
writes the address of the access name table. 


Description 

LIB$GET_ACCNAM_BY_CONTEXT returns the address of the access name table 
for the specified protected object class. The format of the table is a vector of 32 
quadword string descriptors. Each table entry points to the name of an access 
type. The index into the vector is the bit position in an access-desired mask. 
Undefined access types have O-length names. The table can be used as input 
to the LIB$PARSE_SOGW_PROT, LIB$FORMAT_SOGW_PROT, LIB$PARSE_ 
ACCESS.CODE, $PARSE_ACL, and $FORMAT_ACL routines. 
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The semantics of this routine are as follows: 

• If the contxt parameter is not valid, then 

— the routine returns an error status and the value of accnam is 
undefined. 

else 

— accnam points to the table corresponding to the protected object class 
and the routine returns a success status (SS$_NORMAL). 

Condition Values Returned 

SS$_NORMAL Normal successful completion. 

LIB$_WRONUMARG Wrong number of arguments. 

In addition, error status may be returned from $GET_SECURITY. ♦ 
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LIB$GET_COMMAND—Get Line from SYS$COMMAND 

The Get Line from SYS$COMMAND routine gets one record of ASCII text 
from the current controlling input device, specified by the logical name 
SYS$COMMAND. 

Format 

LIB$GET_COMMAND resultant-string [,prompt-string] [,resultant-length] 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Arguments 

resultant-string 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor 

String that LIB$GET_COMMAND gets from SYS$COMMAND. The resultant¬ 
string argument is the address of a descriptor pointing to this string. 

prompt-string 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Prompt message that LIB$GET_COMMAND displays on the controlling terminal. 
The prompt-string argument is the address of a descriptor pointing to the 
prompt. A valid prompt consists of text followed by no carriage-return/line-feed 
combination. A colon(:) and one space are optional. 

resultant-length 

OpenVMS usage word_unsigned 
type word (unsigned) 

access write only 

mechanism by reference 

Number of bytes written into resultant-string by LIB$GET_COMMAND, not 
counting padding in the case of a fixed string. The resultant-length argument 
is the address of an unsigned word containing this length. If the input string 
is truncated to the size specified in the resultant-string descriptor, resultant- 
length is set to this size. Therefore, resultant-length can always be used by the 
calling program to access a valid substring of resultant-string. 


cond_value 
longword (unsigned) 
write only 
by value 
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Description 

LIB$GET_COMMAND uses the RMS $GET service (see the OpenVMS Record 
Management Services Reference Manual) to get one record of ASCII text from the 
current controlling input device, specified by SYS$COMMAND. 

When you log in, the OpenVMS operating system creates three files as default I/O 
control streams for your process. 

• SYS$INPUT, your default input device 

• SYS$OUTPUT, your default output device 

• SYS$COMMAND, the device that supplies the commands to your process 

These files remain open until you log out. They are the interface between 
your interactive input and output or your batch commands and the OpenVMS 
software. Initially, all three files are equated with the terminal. However, 
with the DCL ASSIGN command, you can change these assignments to 
obtain information from a file or put information into a file. SYS$INPUT and 
SYS$COMMAND are usually identical, but the input and command streams can 
be different. For example, during the execution of an indirect command file from 
an interactive terminal, SYS$COMMAND refers to the terminal and SYS$INPUT 
refers to the command file. 

LIB$GET_COMMAND opens file SYS$COMMAND on the first call. The RMS 
internal stream identifier (ISI) is stored in the routine's static storage for 
subsequent calls. 

If prompt-string is provided and if the SYS$COMMAND device is a terminal, 
LIB$GET_COMMAND displays the prompt message. If the device is not a 
terminal, the prompt-string is ignored. 

LIB$GET_COMMAND is used when a program needs input from some source 
other than the current input stream. Usually, it is used to input from the 
terminal rather than from an indirect command file. For example, a program 
may ask a question which cannot be answered by an indirect command file entry. 
In this case the program would call LIB$GET_COMMAND to get one record of 
ASCII text from SYS$COMMAND, the terminal. 

Condition Values Returned 

SS$_NORMAL Routine successfully completed. RMS completion 

status. 

LIB$_FATERRLIB An internal consistency check on Run-Time 

Library data structures has failed. This may 
indicate a programming error in the Run¬ 
Time Library, or that your program may have 
overwritten those data structures. 

LIB$_INPSTRTRU The input string has been truncated to the size 

specified in the resultant-string descriptor 
(fixed-length strings only). Resultant-length is 
also set to this size. This is an error (as opposed 
to LIB$_STRTRU which is a success) because the 
truncation is not under program control. 
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LIB$_INSVIRMEM Insufficient virtual memory to allocate the 

dynamic string. 

LIB$_INVARG Invalid arguments. The descriptor class field is 

not a recognized code or is zero. 

Any valid RMS status code. 

Any code returned by LIB$GET_VM or LIB$SCOPY_R_DX. 
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LIB$GET_COMMON—Get String from Common 

The Get String from Common routine copies a string in the common area to the 
destination string. (The common area is an area of storage which remains defined 
across multiple image activations in a process.) The string length is taken from 
the first longword of the common area. 


Format 

LIB$GET_COMMON resultant-string [,resultant-length] 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Arguments 


resultant-string 

OpenVMS usage 

type 

access 

mechanism 


char_string 
character string 
write only 
by descriptor 


Destination string into which LIB$GET_COMMON writes the string copied from 
the common area. The resultant-string argument is the address of a descriptor 
pointing to the destination string. 


resultant-length 

OpenVMS usage word_unsigned 
type word (unsigned) 

access write only 

mechanism by reference 

Number of characters written into resultant-string by LIB$GET_COMMON, 
not counting padding in the case of a fixed-length string. The resultant-length 
argument is the address of an unsigned word integer containing the number of 
characters copied. If the input string is truncated to the size specified in the 
resultant-string descriptor, resultant-length is set to this size. Therefore, 
resultant-length can always be used by the calling program to access a valid 
substring of resultant-string. 


Description 

LIB$PUT_COMMON allows a program to copy a string into the process’s common 
storage area. This area remains defined during multiple image activations. 
LIB$GET_COMMON allows a program to copy a string from the common area 
into a destination string. The programs reading and writing the data in the 
common area must agree upon its amount and format. 

The maximum number of characters that can be copied is 252. The actual 
number of characters copied is returned by the optional argument, resultant- 
length (if given). 
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You can use LIB$PUT_COMMON and LIB$GET_COMMON to pass information 
between images run successively, such as chained images run by LIB$RUN_ 
PROGRAM. Since the common area is unique to each process, do not use 
LIB$GET_COMMON and LIB$PUT_COMMON to share information across 
processes. 


Condition Values Returned 

SS$_N ORMAL 
LIB$_STRTRU 

LIB$_FATERRLIB 

LIB$_IN SVIRMEM 

LIB$_INVSTRDES 


Routine successfully completed. 

Successfully completed. The string was longer 
than the buffer and was truncated. 

Fatal internal error. An internal consistency 
check has failed. This usually indicates an 
internal error in the Run-Time Library and 
should be reported to Digital. 

Insufficient virtual memory. A call to LIB$GET_ 
VM has failed because your program has 
exceeded the image quota for virtual memory. 

Invalid string descriptor. A string descriptor has 
an invalid value in its DSC$B_CLASS field. 


LIB-188 


LIB$GET_CURR_INVO_CONTEXT 


LIB$GET_CURR_INVO_CONTEXT — Get Current Invocation Context 

The Get Current Invocation Context routine gets the current invocation context 
of any active procedure. 

A thread can obtain the invocation context of a current procedure using the 
following function format: 


Format 

UB$GET_CURRJNVO_CONTEXT invo_context 

Returns 

None. 

Argument 

invo_context 

OpenVMS usage invo_context_blk 
type structure 

access write only 

mechanism by reference 

Address of an invocation context block into which the procedure context of the 
caller will be written. 


Description 

LIB$GET_CURR_INVO_CONTEXT gets the current invocation context of any 
active procedure. 

See the OpenVMS Calling Standard manual for additional information. 

Condition Values Returned 

None. 
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LIB$GET_DATE_FORMAT—Get the User’s Date Input Format 

The Get The User’s Date Input Format routine returns information about the 
user’s choice of a date/time input format. 

Format 

UB$GET_DATE_FORMAT format-string [,user-context] 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Arguments 

format-string 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor 

Receives the translation of LIB$DT_INPUT_FORMAT. The format-string 
argument is the address of a descriptor pointing to this format string. 

user-context 

OpenVMS usage context 
type longword (unsigned) 

access modify 

mechanism by reference 

Context variable that retains the translation context over multiple calls to this 
routine. The user-context argument is the address of an unsigned longword 
that contains this context. The initial value of the context variable must be zero. 
Thereafter, the user program must not write to the cell. 

The user-context argument is optional. However, if a context cell is not passed, 
the routine LIB$GET_DATE_FORMAT may abort if two threads of execution 
attempt to manipulate the context area concurrently. Therefore, when calling 
this routine in situations where reentrancy might occur, such as from AST level, 
Digital recommends that users specify a different context cell for each calling 
thread. 

Description 

Depending on which method was used to specify the input formats, LIB$GET_ 
DATE_FORMAT either translates the logicals LIB$DT_INPUT_FORMAT and 
LIB$FORMAT_MNEMONICS, or uses the preinitialized context components 
LIB$K_FORMAT_MNEMONICS and LIB$K_INPUT_FORMAT to return the 
user’s specified date/time input format in a “legible” form. This format-string 
can then be used as a guideline for entering date/time strings. 


cond_value 
longword (unsigned) 
write only 
by value 


LIB-190 





LIB$GET_DATE_FORMAT 


The string returned by LIB$GET_DATE_FORMAT parallels the currently defined 
input format string, consisting of the format punctuation (with most whitespace 
compressed) and “legible” mnemonics representing the various format fields. The 
English (default) versions of these mnemonics are as follows: 


Format Field 

Legible Mnemonic (Default) 

Year 

YYYY 1 

Numeric month 

MM 

Alphabetic month 

MONTH 

Numeric day 

DD 

Hours (12- or 24-hour) 

HH 

Minutes 

MM 

Seconds 

ss 

Fractional seconds 

cc 1 

Meridiem indicator 

AM/PM 

lr This variable-length field mnemonic has a numeric suffix representing the number of digits allowed 
/required in the field. For instance, YYYY4 indicates a four-digit year field. 


For example, consider the following input format string: 

$ DEFINE LIB $ DT_INPUT_FORMAT - 

_$ "!MAAU !DO, 1Y2 1H02:!M0:ISO.!C4 IMIU" 

If LIB$GET_DATE_FORMAT were called for this format string, the format string 
returned would be as follows: 

MONTH DD, YYYY2 HH:MM:SS.CC4 AM/PM 


Condition Values Returned 


SS$_N ORMAL 
LIB$_DEFFORUSE 

LIB$_ENGLUSED 

LIB$_ILLFORMAT 

LIB$_INVARG 

LIB$_INVSTRDES 

LIB$_REENTRANCY 

LIB$_STRTRU 

LIB$_UNRFORCOD 

LIB$_WRONUMARG 


Normal successful completion. 

Default format used; unable to determine desired 
format. 

English used; unable to determine or use desired 
language. 

Illegal format string. 

Invalid argument; a required argument was not 
specified. 

Invalid input string descriptor. 

Reentrancy detected. 

String truncated. 

Unrecognized format code. 

Wrong number of arguments. 


Any condition value returned by LIB$GET_VM, LIB$SCOPY_R_DX, and 
LIB$SFREE1_DD. 
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LIB$GET_EF—Get Event Flag 

The Get Event Flag routine allocates one local event flag from a process-wide 
pool and returns the number of the allocated flag to the caller. If no flags are 
available, LIB$GET_EF returns an error as its function value. 


Format 

LIB$GET_EF event-flag-number 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Argument 

event-flag-number 

OpenVMS usage ef_number 
type longword (unsigned) 

access write only 

mechanism by reference 

Number of the local event flag that LIB$GET_EF allocated, or -1 if no local event 
flag was available. The event-flag-number argument is the address of a signed 
longword integer into which LIB$GET_EF writes the number of the local event 
flag that it allocates. 


Description 

LIB$GET_EF and LIB$FREE_EF cause local event flags to be allocated and 
deallocated at run time, so that your routine remains independent of other 
routines executing in the same process. 

The following table lists status of local event flags. 


Number Status 

0 Never used by this routine and always available 

1 to 23 Initially reserved; available after being freed by LIB$FREE_EF 
24 to 31 Reserved to OpenVMS 

32 to 63 Initially free 


Local event flags numbered 32 to 63 are available to your program. These event 
flags allow routines to communicate and synchronize their operations. 

Using LIB$GET_EF provides your program with an arbitrary event flag number. 
You can obtain a specific event flag number by calling LIB$RESERVE_EF. 
and passing as an argument the number of the specific event flag that you 
wish to reserve. However, reserving a specific local event flag number is not 
recommended. If you use a specific event flag in your routine, another routine 
may attempt to use the same flag, and the flag will no longer function as 
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expected. Therefore, you should call LIB$GET_EF to obtain the next arbitrary 
event flag and LIB$FREE_EF to return it to the storage pool. 

Condition Values Returned 

SS$_NORMAL Routine successfully completed. 

LIB$_INSEF Insufficient event flags. There were no more 

event flags available for allocation. 
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LIB$GET_FOREIGN—Get Foreign Command Line 

The Get Foreign Command Line routine requests the calling image’s Command 
Language Interpreter (CLI) to return the contents of the “foreign command” line 
that activated the current image. 


Format 


LIB$GET_FOREIGN resultant-string [,prompt-string] [,resultant-length] [.flags] 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Arguments 


resultant-string 

OpenVMS usage 

type 

access 

mechanism 


char_string 
character string 
write only 
by descriptor 


String which LIB$GET_FOREIGN uses to receive the foreign command line. The 
resultant-string argument is the address of a descriptor pointing to this string. 
If the foreign command text returned was obtained by prompting to SYS$INPUT 
(see the description of flags), the text is translated to uppercase so as to be more 
consistent with text returned from the CLI. 


prompt-string 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Optional user-supplied prompt for text which LIB$GET_FOREIGN uses if no 
command-line text is available. The prompt-string argument is the address of 
a descriptor pointing to the user prompt. If omitted, no prompting is performed. 
It is recommended that prompt-string be specified. If prompt-string is omitted 
and if no command-line text is available, a zero-length string will be returned. 

resultant-length 

OpenVMS usage word_unsigned 
type word (unsigned) 

access write only 

mechanism by reference 

Number of bytes written into resultant-string by LIB$GET_FOREIGN, not 
counting padding in the case of a fixed-length resultant-string. The resultant- 
length argument is the address of an unsigned word into which LIB$GET_ 
FOREIGN writes the number of bytes. 
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flags 

OpenVMS usage mask_longword 
type longword (unsigned) 

access modify 

mechanism by reference 

Value which LIB$GET_FOREIGN uses to control whether or not prompting is 
to be performed. The flags argument is the address of an unsigned longword 
integer containing this value. If the low bit of flags is zero, or if flags is omitted, 
prompting is done only if the CLI does not return a command line. If the low 
bit is 1, prompting is done unconditionally. If specified, flags is set to 1 before 
returning to the caller. 

The primary use of flags is to allow a utility program to be invoked once 
with subcommand text on the command line, and then to repeatedly prompt 
for further subcommands from SYS$INPUT. This is accomplished by calling 
LIB$GET_FOREIGN repeatedly, specifying in the call a prompt-string string 
and a flags variable which is initialized to zero at the beginning of the program. 
The first call gets the subcommand text from the command line, after which flags 
will be set to 1, causing further subcommands to be requested through prompts 
to SYS$INPUT. 


Description 

LIB$GET_FOREIGN returns the contents of the command line that you use to 
activate an image. It can be used to give your program access to the qualifiers of 
a foreign command or to prompt for further command line text. 

A foreign command is a command that you can define and then use as if it were 
a DCL or MCR command in order to run a program. When you use the foreign 
command at command level, the CLI parses the foreign command only and 
activates the image. It ignores any options or qualifiers that you have defined for 
the foreign command. Once the CLI has activated the image, the program can 
call LIB$GET_FOREIGN to obtain and parse the remainder of the command line 
(after the command itself) for whatever options it may contain. See the OpenVMS 
User's Manual for information on how to define a foreign command. 

If no command line is available, LIB$GET_FOREIGN can optionally call 
LIB$GET_INPUT to prompt the user for command text. If desired, LIB$GET_ 
FOREIGN can be called repetitively, returning the command line on the first call, 
but prompting for further text on subsequent calls. 

LIB$GET_FOREIGN can also be used for images invoked by the RUN command, 
for which further text must be obtained by prompting. Such an image can also 
be invoked by the DCL command MCR or by the MCR Command Language 
Interpreter. The text following the image name will be returned to the executing 
image. 

The action of LIB$GET_FOREIGN depends on the environment in which the 
image is activated. 

• If you use a foreign command to invoke the image, you can call LIB$GET_ 
FOREIGN to obtain the command qualifiers following the foreign command. 
You can also use LIB$GET_FOREIGN to prompt repeatedly for more 
qualifiers after the command. This technique is shown in the example. 
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• If the image is in the SYS$SYSTEM: directory, the image can be invoked by 
the DCL MCR command or by the MCR Command Language Interpreter. In 
this case, LIB$GET_FOREIGN returns the command line text following the 
image name. 

• If the image is invoked by a DCL RUN command, LIB$GET_FOREIGN can 
be used to prompt for additional text. 

• If the image is not invoked by a foreign command or MCR, or if there is no 
information remaining on the command line, and the user-supplied prompt 
is present, LIB$GET_INPUT is called to prompt for a command line. If the 
prompt is not present, LIB$GET_FOREIGN returns a zero length string. 


Condition Values Returned 


SS$_N ORMAL 

LIB$_FATERRLIB 

LIB$_INPSTRTRU 


LIB$_IN SVIRMEM 
LIB$_INVSTRDES 


Routine successfully completed. 

A fatal internal error was detected. 

The input string was truncated. Resultant- 
stringing could not contain all of the characters. 
Resultant-length reflects the truncated length. 
Insufficient virtual memory. 

Invalid string descriptor. 


A condition value returned by RMS. SYS$INPUT was prompted for command 
text and RMS returned an error. The most typical error will be RMS$_EOF, 
end-of-file. 


Example 


EXAMPLE: ROUTINE OPTIONS (MAIN); 

%INCLUDE $STSDEF; /* Status-testing definitions */ 

DECLARE COMMAND_LINE CHARACTER(80) VARYING, 

PROMPT_FLAG FIXED BINARY(31) INIT(O), 
LIB$GET_FOREIGN ENTRY (CHARACTER(*) VARYING, 

CHARACTER(*) VARYING, 
FIXED BINARY(15), 

FIXED BINARY(31)) 

OPTIONS(VARIABLE) RETURNS (FIXED BINARY(31)), 
RMS$_EOF GLOBALREF FIXED BINARY(31) VALUE; 

/* Repeat forever calling LIB$GET_FOREIGN to obtain 
subcommand text and print the text. Exit when an 
end-of-file is found. */ 

DO WHILE ('1'B); /* Do while TRUE */ 

STS$VALUE = LIB$GET_FOREIGN 

(COMMAND_LINE,'Input: ',, 

PROMPT_FLAG); 

IF STS$SUCCESS THEN 

PUT LIST (' Command was ',COMMAND_LINE); 

ELSE DO; 

IF STS$VALUE A = RMS$_EOF THEN 
PUT LIST ('Error encountered'); 

RETURN; 

END; 

PUT SKIP; /* Skip to next line */ 

END; /* End of DO WHILE loop */ 

END; 
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This PL/I example shows the use of the optional flags argument to permit 
repeated calls to LIB$GET_FOREIGN. The command line text is retrieved on the 
first pass only; after the first pass, the program prompts from SYS$INPUT. 
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LIB$GET_INPUT—Get Line from SYS$INPUT 

The Get Line from SYS$INPUT routine gets one record of ASCII text from the 
current controlling input device, specified by SYS$INPUT. 

Format 

UB$GET_INPUT resultant-string [.prompt-string] [.resultant-length] 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Arguments 

resultant-string 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor 

String that LIB$GET_INPUT gets from the input device. The resultant-string 
argument is the address of a descriptor pointing to the character string into 
which LIB$GET_INPUT writes the text received from the current input device. 

prompt-string 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Prompt message that is displayed on the controlling terminal. The prompt¬ 
string argument is the address of a descriptor containing the prompt. A 
valid prompt consists of text followed by a colon (:), a space, and no carriage- 
return/line-feed combination. The maximum size of the prompt message is 255 
characters. If the controlling input device is not a terminal, this argument is 
ignored. 

resultant-length 

OpenVMS usage word_unsigned 
type word (unsigned) 

access write only 

mechanism by reference 

Number of bytes written into resultant-string by LIB$GET_INPUT, not 
counting padding in the case of a fixed string. The resultant-length argument 
is the address of an unsigned word containing this number. If the input string 
is truncated to the size specified in the resultant-string descriptor, resultant- 
length is set to this size. Therefore, resultant-length can always be used by the 
calling program to access a valid substring of resultant-string. 
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Description 

LIB$GET_INPUT uses the RMS $GET service to get one record of ASCII text 
from the current controlling input device, specified by SYS$INPUT. (For more 
information about the RMS $GET service see the OpenVMS Record Management 
Services Reference Manual.) 

When you log in, the OpenVMS operating system creates three files as default I/O 
control streams for your process. 

• SYS$INPUT, your default input device 

• SYS$OUTPUT, your default output device 

• SYS$COMMAND, the device that supplies the commands to your process 

These files remain open until you log out. They are the interface between 
your interactive input and output or your batch commands and the OpenVMS 
software. Initially, all three names are equated with the terminal. However, 
with the DCL ASSIGN command, you can change these assignments to 
obtain information from a file or put information into a file. SYS$INPUT and 
SYS$COMMAND are usually identical, but the input and command streams can 
be different. For example, during the execution of an indirect command file from 
an interactive terminal, SYS$COMMAND refers to the terminal and SYS$INPUT 
refers to the command file. 

LIB$GET_INPUT opens file SYS$INPUT on the first call. The RMS internal 
stream identifier (ISI) is stored in the routine’s static storage for subsequent calls. 
Hence, this routine is not AST reentrant. 

If prompt-string is provided and the SYS$INPUT device is a terminal, 
LIB$GET_INPUT displays the prompt message. If the device is not a terminal, 
the prompt-string argument is ignored. 

If you wish to get input from some source other than the current input stream, 
use LIB$GET_COMMAND. 


Condition Values Returned 

SS$_N ORMAL 

LIB$_FATERRLIB 


LIB$_INPSTRTRU 


LIB$_IN SVIRMEM 


Routine successfully completed. RMS completion 
status. 

An internal consistency check on Run-Time 
Library data structures has failed. This may 
indicate a programming error in the Run¬ 
Time Library, or that your program may have 
overwritten those data structures. 

The input string has been truncated to the size 
specified in the resultant-string descriptor 
(fixed-length strings only). Resultant-length is 
also set to this size. This is an error (as opposed 
to LIB$_STRTRU which is a success) because the 
truncation is not under program control. 

Insufficient virtual memory to allocate the 
dynamic string. 
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LIB$_INVARG Invalid arguments. The descriptor class field is 

not a recognized code or is zero. 

Any RMS condition value returned by $GET. 

Any condition value returned by LIB$GET_VM or LIB$SCOPY_R_DX. 


LIB-200 


LIB$GETJNVO_CONTEXT 


LIB$GET_INVO_CONTEXT — Get Invocation Context 

The Get Invocation Context routine gets the invocation context of any active 
procedure. 


Format 

LIB$GET_INVO_CONTEXT invo_handle, invo_context 

Returns 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access write only 

mechanism by value 

A value of 1 indicates success; a value of 0 indicates failure. 

Arguments 

invo_handle 

OpenVMS usage invo_handle 
type longword (unsigned) 

access read only 

mechanism by value 

Handle for the desired invocation. Returned by LIB$GET_INVO_HANDLE. 

invo_context 

OpenVMS usage invo_context_blk 
type structure 

access write only 

mechanism by reference 

Address of an invocation context block into which the procedure context of the 
frame specified by invo_handle will be written. 


Description 

LIB$GET_INVO_CONTEXT gets the invocation context of any active procedure. 

_ Note _ 

If the invocation handle that was passed does not represent any procedure 
context in the active call chain, the value of the new contents of the 
context block is unpredictable. 


See the OpenVMS Calling Standard manual for additional information. 

Condition Values Returned 

None. 
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LIB$GET_INVO_HANDLE — Get Invocation Handle 

The Get Invocation Handle routine gets an invocation handle of any active 
procedure. 

A thread can obtain an invocation handle corresponding to any invocation context 
block by using the following function format. 


Format 

LIB$GETJNVO_HANDLE invo_context 

Returns 

OpenVMS usage invo_handle 
type longword (unsigned) 

access write only 

mechanism by value 

Invocation handle of the invocation context that was passed. If the returned 
value is LIB$K_INVO_HANDLE_NULL, the invocation context that was passed 
was invalid. 

Argument 

invo_context 

OpenVMS usage invo_context_blk 
type structure 

access read only 

mechanism by reference 

Address of an invocation context block. Here, only the frame pointer and stack 
pointer fields of an invocation context block must be defined. 


Description 

LIB$GET_INVO_HANDLE gets an invocation handle of any active procedure. 
See the OpenVMS Calling Standard manual for additional information. 

Condition Values Returned 

None. 
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LIB$GET_LUN—Get Logical Unit Number 

The Get Logical Unit Number routine allocates one logical unit number from 
a process-wide pool. If a unit is available, its number is returned to the caller. 
Otherwise, an error is returned as the function value. 


Format 

UB$GET_LUN logical-unit-number 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Argument 

logical-unit-number 

OpenVMS usage longword_signed 
type longword integer (signed) 

access write only 

mechanism by reference 

Allocated logical unit number or —1 if none was available. The logical-unit- 
number argument is the address of a longword into which LIB$GET_LUN 
returns the value of the allocated logical unit. The logical unit numbers that 
LIB$GET_LUN can allocate are in the range 100 through 119. 


Description 

LIB$GET_LUN allocates one logical unit number from a process-wide pool. If 
a unit is available, its number is returned to the caller. Otherwise, an error is 
returned as the function value. 

LIB$GET_LUN reserves the logical unit numbers 100 through 119. This routine 
assumes that the logical unit numbers in the range 0 through 99 may be in use 
by your program, but it cannot determine which logical unit numbers are actually 
in use by your program. 

You should call LIB$GET_LUN only from FORTRAN or BASIC programs. Those 
languages and LIB$GET_LUN share the concept of unit numbers and a similar 
number space. 

Condition Values Returned 

SS$_N ORMAL 
LIB$_INSLUN 


Routine successfully completed. 

Insufficient logical unit numbers. No logical unit 
numbers were available. 
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LIB$GET_MAXIMUM_DATE_LENGTH—Retrieve the Maximum 

Length of a Date/Time String 

Given an output format and language, the Retrieve the Maximum Length of 
a Date/Time String routine determines the maximum possible length for the 
date-string string returned by LIB$FORMAT_DATE_TIME. 

Format 

LIB$GET_MAXIMUM_DATE_LENGTH date-length [,user-context] [.flags] 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Arguments 

date-length 

OpenVMS usage longword_signed 
type longword (signed) 

access write only 

mechanism by reference 

Receives the maximum possible length of the date-string argument returned 
to LIB$FORMAT_DATE_TIME. The date-length argument is the address of 
a signed longword that receives this maximum length. The length written to 
date-length reflects the greatest possible length of an output date/time string for 
the currently selected output format and natural language. 

For example, if the selected output date/time format includes the alphabetic, 
unabbreviated month name (assuming English as the natural language), the 
longest month name (September) would have to be taken into consideration when 
determining the maximum possible length of date-string. 

user-context 

OpenVMS usage context 
type longword (unsigned) 

access modify 

mechanism by reference 

Context variable that retains the translation context over multiple calls to this 
routine. The user-context argument is the address of an unsigned longword 
that contains this context. The initial value of the context variable must be zero. 
Thereafter, the user program must not write to the cell. 

The user-context parameter is optional. However, if a context cell is not passed, 
the routine LIB$GET_MAXIMUM_DATE_LENGTH may abort if two threads of 
execution attempt to manipulate the context area concurrently. Therefore, when 
calling this routine in situations where reentrancy might occur, such as from 
AST level, Digital recommends that users specify a different context cell for each 
calling thread. 


LIB-204 


LIB$GET_MAXIMUM_DATE_LENGTH 


flags 

OpenVMS usage mask_longword 
type longword (unsigned) 

access read only 

mechanism by reference 

Bit mask that allows the user to specify whether the date, time, or both are to be 
included in the calculation of the maximum date length. The flags argument is 
the address of an unsigned bit mask containing the specified values. Valid values 
are LIB$M_DATE_FIELDS and LIB$M_TIME_FIELDS. The values specified for 
flags must correspond to the flags argument passed to LIB$FORMAT_DATE_ 
TIME. 

Description 

The LIB$GET_MAXIMUM_DATE_LENGTH routine determines the maximum 
possible length for a formatted date/time string as returned by LIB$FORMAT_ 
DATE_TIME. The maximum length returned takes into account the currently 
specified output format and natural language; date-length represents the 
maximum possible length of the string written to the date-string argument of 
LIB$FORMAT_DATE_TIME. 

Consider the following example, in which the output format is defined as follows. 
DEFINE LIB$DT_FORMAT LIB$DATE_FORMAT_012, LIB$TIME_FORMAT_012 
This date/time format would appear as follows: 

!MAU !DD, !Y4 !HH2:!M0 !MIU 

Given this format, the maximum possible length for this date/time string is 
calculated using the longest possible date string followed by a space and the 
longest possible time string. One example that meets these requirements is as 
follows (assuming English as the selected language): 

SEPTEMBER 21, 1994 11:24 PM 

The maximum possible length of this date-string would then be 28. 

Condition Values Returned 

SS$_NORMAL Normal successful completion. 

LIB$_ENGLUSED English used by default; unable to translate 

SYS$LANGUAGE. 

LIB$_DEFFORUSE Default format used; unable to determine desired 

format. 

LIB$_UNRFORCOD Unrecognized format code. 

LIB$_STRTRU Output string truncated. 

LIB$_ABSTIMREQ Absolute time required. 

LIB$_REENTRANCY Reentrant invocation with same context variable. 

Any condition value returned by LIB$GET_VM. 
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LIB$GET_PREV_INVO_CONTEXT—Get Previous Invocation Context 


The Get Previous Invocation Context routine gets the previous invocation context 
of any active procedure. 

A thread can obtain the invocation context of the procedure context preceding any 
other procedure context using the following function format. 


Format 

LIB$GET_PREV_INVO_CONTEXT invo_context 

Returns 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access write only 

mechanism by value 

Status value. A value of 1 indicates success. When the initial context represents 
the bottom of the call chain, a value of 0 is returned. 

Argument 

invo_context 

OpenVMS usage invo_context_blk 
type structure 

access modify 

mechanism by reference 

Address of an invocation context block. The given context block is updated to 
represent the context of the previous (calling) frame. 

For the purposes of this function, the minimum fields of an invocation block 
that must be defined are those IREG and FREG fields corresponding to registers 
used by a context whether the registers are preserved or not. Note that the 
invocation context blocks written by the routines specified in these sections define 
all possible fields in a context block. Such context blocks satisfy this minimum 
requirement. 


Description 

LIB$GET_PREV_INVO_CONTEXT gets the previous invocation context of any 
active procedure. 

See the OpenVMS Calling Standard manual for additional information. 

Condition Values Returned 

None. 
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LIB$GET_PREV_INVO_HANDLE — Get Previous Invocation Handle 

The Get Previous Invocation Handle routine gets the previous invocation handle 
of any active procedure. 

A thread can obtain an invocation handle of the procedure context preceding that 
of a specified procedure context by using the following function format. 


Format 

LIB$GET_PREV_INVO_HANDLE invo.handle 

Returns 

OpenVMS usage invo_handle 
type longword (unsigned) 

access write only 

mechanism by value 

An invocation handle for the invocation context that is previous to that which 
was specified as the target. 

Argument 

invo_handle 

OpenVMS usage invo_handle 
type longword (unsigned) 

access read only 

mechanism by value 

An invocation handle that represents a target invocation context. 


Description 

LIB$GET_PREV_INVO_HANDLE gets the previous invocation handle of any 
active procedure. 

See the OpenVMS Calling Standard manual for additional information. 

Condition Values Returned 

None. 
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LIB$GET_SYMBOL—Get Value of CLI Symbol 


The Get Value of CLI Symbol routine requests the calling process’s Command 
Language Interpreter (CLI) to return the value of a CLI symbol as a string. 
LIB$GET_SYMBOL then returns the string to the caller. Optionally, LIB$GET_ 
SYMBOL can return the length of the returned value and the table in which the 
symbol was found. 


Format 


LIB$GET_SYMBOL symbol , resultant-string [,resultant-length] [,table-type-indicator] 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Arguments 


symbol 

OpenVMS usage 

type 

access 

mechanism 


char_string 
character string 
read only 
by descriptor 


Name of the symbol for which LIB$GET_SYMBOL searches. The symbol 
argument is the address of a descriptor pointing to the name of the symbol. 
LIB$GET_SYMBOL converts the symbol name to uppercase and removes trailing 
blanks before the search. Symbol must begin with a letter, a digit, a dollar sign 
($), a hyphen (-), or an underscore (_). The maximum length of symbol is 255 
characters. 


resultant-string 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor 

Value of the returned symbol. The resultant-string argument is the address of 
a descriptor pointing to a character string into which LIB$GET_SYMBOL writes 
the value of the symbol. 

resultant-length 

OpenVMS usage word_unsigned 
type word (unsigned) 

access write only 

mechanism by reference 

Length of the symbol value returned by LIB$GET_SYMBOL. The resultant- 
length argument is the address of an unsigned word integer into which 
LIB$GET_SYMBOL writes the length. 
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table-type-indicator 

OpenVMS usage longword_signed 
type longword integer (signed) 

access write only 

mechanism by reference 

Indicator of which table contained the symbol. The table-type-indicator 
argument is the address of a signed longword integer into which LIB$GET 
SYMBOL writes the table indicator. 

Possible values of the table indicator are listed below. 


Symbolic Name 

Value 

Table 

LIB$K_CLI_LOCAL_SYM 

1 

Local symbol table 

LIB$K_CLI_GLOBAL_SYM 

2 

Global symbol table 


LIB$K_CLI_LOCAL_SYM and LIB$K_CLI_GLOBAL_SYM are defined in Digital 
supplied symbol libraries (macro or module name $LIBCLIDEF) and as global 
symbols. 


Description 

LIB$GET_SYMBOL first searches the local symbol table for the symbol name, 
then searches the global symbol table. Numeric values are converted to an ASCII 
representation of a signed decimal number before being returned. 

LIB$GET_SYMBOL is supported for use with the DCL Command Language 
Interpreter. If used with the MCR CLI, the error status LIB$_NOCLI will be 
returned. 

If an image is run directly as a subprocess or as a detached process, there is no 
CLI present to get the symbol. In that case, LIB$GET_SYMBOL returns the 
error status LIB$_NOCLI. 

Condition Values Returned 

SS$_NORMAL Routine successfully completed. 

LIB$_STRTRU Routine successfully completed; string truncated. 

The destination string could not contain all the 
characters in the symbol value. 

LIB$_FATERRLIB Fatal internal error. An internal consistency 

check has failed. This usually indicates an 
internal error in the Run-Time Library and 
v should be reported to Digital in a Software 

Performance Report (SPR). 

LIB$_INSCLIMEM Insufficient CLI memory. The CLI could not 

obtain enough virtual memory to perform the 
function. This may be caused by having too 
many symbols defined. Deleting some symbol 
definitions may relieve the situation. 
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LIB$_IN S VIRMEM 

LIB$_INVSTRDES 

LIB$_INVSYMNAM 

LIB$_NOCLI 

LIB$_NOSUCHSYM 

LIB$_UNECLIERR 


Insufficient virtual memory. A call to LIB$GET_ 
VM has failed because your program has 
exceeded the image quota for virtual memory 

Invalid string descriptor. A string descriptor has 
an invalid value in its DSC$B_CLASS field. 

Invalid symbol name. The symbol name 
contained more than 255 characters or did not 
begin with a letter or dollar sign ($). 

No CLI present. The calling process did not have 
a CLI to perform the function or the CLI did not 
support the request type. Note that an image 
run as a subprocess or detached process does not 
have a CLI. 

No such symbol. The symbol was not defined in 
either the local or global symbol table. 

Unexpected CLI error. The CLI returned an 
error status which was not recognized. This 
error may be caused by use of a nonstandard 
CLI. If this error occurs while using the DCL 
Command Language Interpreter, please report 
the problem to Digital in a Software Performance 
Report (SPR). 
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LIB$GET_USERS_LANGUAGE—Return the User’s Language 

The Return the User’s Language routine determines the user’s choice of a natural 
language. The choice is determined by translating the logical SYS$LANGUAGE. 


Format 

LIB$GET_USERS_LANGUAGE language 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Argument 


language 

OpenVMS usage 

type 

access 

mechanism 


char_string 
character string 
write only 
by descriptor 


Receives the translation of SYS$LANGUAGE. The language argument is the 
address of a descriptor pointing to this language name. 


Description 

The LIB$GET_USERS_LANGUAGE routine translates the logical 
SYS$LANGUAGE and returns the user’s choice of a natural language. If the 
logical SYS$LANGUAGE does not translate for some reason, then the language 
defaults to English and the status LIB$_ENGLUSED is returned. 

If a failure or truncation occurs while copying the language name to the 
language string argument, that error status overrides the LIB$_ENGLUSED or 
SS$_NORMAL status. 

Condition Values Returned 

SS$_NORMAL Normal successful completion. 

LIB$_ENGLUSED English used by default; unable to translate 

SYS$LANGUAGE. 

Any condition value returned by LIB$SCOPY_R_DX. 
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LIB$GET_VM—Allocate Virtual Memory 

The Allocate Virtual Memory routine allocates a specified number of contiguous 
bytes in the program region and returns the virtual address of the first byte 
allocated. 


Format 

LIB$GET_VM number-of-bytes, base-address [,zone-id] 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Arguments 


number-of-bytes 

OpenVMS usage 

type 

access 

mechanism 


longword_signed 
longword integer (signed) 
read only 
by reference 


Number of contiguous bytes that LIB$GET_VM allocates. The number-of- 
bytes argument is the address of a longword integer containing the number 
of bytes. LIB$GET_VM allocates enough memory to satisfy the request. Your 
program should not reference an address before the first byte address allocated 
(base-address) or beyond the last byte allocated (base-address + number-of- 
bytes — 1) since that space may be assigned to another routine. The value of 
number-of-bytes must be greater than zero. 


base-address 

OpenVMS usage address 
type longword (unsigned) 

access write only 

mechanism by reference 

First virtual address of the contiguous block of bytes allocated by LIB$GET_VM. 
The base-address argument is the address of an unsigned longword containing 
this base address. 


zone-id 

OpenVMS usage 

type 

access 

mechanism 


identifier 

longword (unsigned) 
read only 
by reference 


The zone-id argument is the address of a longword that contains a zone identifier 
created by a previous call to LIB$CREATE_VM_ZONE or LIB$CREATE_USER_ 
VM_ZONE. This argument is optional. If zone-id is omitted or if the longword 
contains the value 0, LIB$VM’s default zone is used. 
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Description 

LIB$GET_VM satisfies an allocation request by reusing free memory in the zone, 
or by obtaining additional memory from the processwide page pool managed by 
LIB$GET_VM_PAGE. 

LIB$GET_VM rounds up the value of number-of-bytes to a multiple of the 
block-size specified for the zone. The first byte allocated is aligned on the 
boundary specified by the alignment value for the zone. 

If you specified allocation filling when you created the zone, LIB$GET_VM will 
fill each byte allocated. Otherwise, LIB$GET_VM does not initialize the memory 
and its contents are unpredictable. 

All memory allocated by LIB$GET_VM has user mode read/write access, even if 
the call to LIB$GET_VM was made from a more privileged access mode. 

The space allocated by successive calls to LIB$GET_VM may be noncontiguous 
because another routine can call LIB$GET_VM between your calls. If AST 
interrupts occur, LIB$GET_VM may allocate space to another routine between 
execution of any two statements in your program. Even if successive calls to 
LIB$GET_VM return two contiguous blocks, you must not combine them into one 
large block that is freed by a single call to LIB$FREE_VM. 

LIB$GET_VM is fully reentrant, so it may be called by routines executing at AST 
level or in an Ada multitasking environment. 

Your program must retain the address of the allocated area. This allows you to 
access or deallocate the space later. 

If the zone you are getting was created using the LIB$CREATE_USER_VM_ 
ZONE routine, then you must have an appropriate action routine for the get 
operation. That is, in your call to LIB$CREATE_USER_VM_ZONE, you must 
have specified a user-get-routine. 


Condition Values Returned 

SS$_N ORMAL 
LIB$_INSVIRMEM 


lib$_badblosiz 


lib$_badbloadr 

LIB$_PAGLIMEXC 


Routine successfully completed. 

Insufficient virtual memory. The request 
required more dynamic memory than was 
available from the operating system. No partial 
allocation is made in this case. 

Bad block size. The value of number-of-bytes 
was less than or equal to zero. For the fixed size 
blocks algorithm, LIB$_BADBLOSIZ can also be 
generated if the value of algorithm-argument 
specified in the call to LIB$CREATE_VM_ZONE 
is less than number-of-bytes. 

Invalid zone-id or a corrupt zone. 

Allocation exceeds the page-limit, set when the 
zone was create. 
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LIB$GET_VM_PAGE—Get Virtual Memory Page 

The Get Virtual Memory Page routine allocates a specified number of contiguous 
pages on VAX systems or pagelets on AXP systems of memory in the program 
region and returns the virtual address of the first allocated page on VAX or 
pagelet on AXP. 


Format 

UB$GET_VM_PAGE number-of-pages ,base-address 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Arguments 


number-of-pages 

OpenVMS usage 

type 

access 

mechanism 


longword_signed 
longword integer (signed) 
read only 
by reference 


Number of pages on VAX systems or pagelets on AXP systems. The number-of- 
pages argument is the address of a longword integer which specifies the number 
of contiguous pages on VAX systems or pagelets on AXP systems to be allocated. 
The value of number-of-pages must be greater than zero. 


base-address 

OpenVMS usage address 
type longword (unsigned) 

access write only 

mechanism by reference 

Block address. The base-address argument is the address of a longword which 
is set to the address of the first byte of the newly allocated block of pages on VAX 
systems or pagelets on AXP systems. 


Description 

LIB$GET_VM_PAGE allocates blocks of contiguous (512 byte) pages on VAX 
systems and pagelets on AXP systems in the program region. LIB$GET_VM_ 
PAGE manages a processwide pool of free pages. If there are not enough 
contiguous free pages or pagelets to satisfy an allocation request, additional pages 
are created by calling the system service $EXPREG. All memory allocated by 
LIB$GET_VM_PAGE is pagelet aligned; that is, the low-order nine bits of the 
base address are zero. 

All memory allocated by LIB$GET_VM_PAGE has user-mode read/write access, 
even if the call to LIB$GET_VM_PAGE is made from a more privileged access 
mode. 

The contents of memory allocated by LIB$GET_VM_PAGE are unpredictable. 
Your program must assign values to all locations that it uses. 
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LIB$GET_VM_PAGE is designed for request sizes ranging from one page or 
pagelet to a few hundred pages or pagelets. For very large request sizes (over 
1000 pages or pagelets in a single request), you should call the system service 
$EXPREG. 

LIB$GET_VM_PAGE is fully reentrant, so it can be called by routines executing 
at AST level or in an Ada multitasking environment. 


Condition Values Returned 

SS$_N ORMAL 
LIB$JBADBLOSIZ 

LIB$_IN SVIRMEM 


Normal successful completion. 

The value of the argument num_pages is less 
than or equal to 0. 

Insufficient virtual memory. The request 
required more dynamic memory than was 
available from the operating system. No partial 
allocation is made in this case. 
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LIB$GETDVI—Get Device/Volume Information 

The Get Device/Volume Information routine provides a simplified interface to 
the $GETDVI system service. It returns information about the primary and 
secondary device characteristics of an I/O device. The calling process need not 
have a channel assigned to the device about which it wants information. 

Format 

UB$GETDVI item-code [.channel] [.device-name] [.longword-integer-value] [.resultant-string] 
[.resultant-length] 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Arguments 

item-code 

OpenVMS usage longword_signed 
type longword (signed) 

access read only 

mechanism by reference 

Code specifying the item of information you are requesting. The item-code 
argument is the address of a signed longword containing the item code. All valid 
$GETDVI item codes whose names begin with DVI$_ are accepted. 

See the Description section for more information on item codes. 

channel 

OpenVMS usage channel 
type word (unsigned) 

access read only 

mechanism by reference 

OpenVMS I/O channel assigned to the device for which LIB$GETDVI returns 
information. The channel argument is the address of an unsigned word 
containing the channel specification. If channel is not specified, device-name is 
used instead. You must specify either channel or device-name, but not both. If 
neither is specified, the error status SS$_IVDEVNAM is returned. 

device-name 

OpenVMS usage device_name 
type character string 

access read only 

mechanism by descriptor 

Name of the device for which LIB$GETDVI returns information. The device¬ 
name argument is the address of a descriptor pointing to the device name string. 
If this string contains a colon, the colon and the characters that follow it are 
ignored. 


cond_value 
longword (unsigned) 
write only 
by value 
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The device-name may be either a physical device name or a logical name. If 
the first character in the string is an underscore character (_), the name is 
considered a physical device name. Otherwise, the name is considered a logical 
name, and logical name translation is performed until either a physical device 
name is found or the system default number of translations has been performed. 

If device-name is not specified, channel is used instead. You must specify 
either channel or device-name, but not both. If neither is specified, the error 
status SS$_IVDEVNAM is returned. The device name must not be longer than 
255 characters. 

longword-integer-value 

OpenVMS usage longword_signed 
type longword (signed) 

access write only 

mechanism by reference 

Numeric value of the information requested. The longword-integer-value 
argument is the address of a signed longword containing the numeric value. If an 
item is listed as only returning a string value, this argument is ignored. 

resultant-string 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor 

String representation of the information requested. The resultant-string 
argument is the address of a descriptor pointing to this information. If resultant¬ 
string is not specified and if the value returned has only a string representation, 
the error status LIB$_INVARG is returned. 

Refer to Table LIB-3 for a description of the string representation used for each 
item. 

resultant-length 

OpenVMS usage word_unsigned 
type word (unsigned) 

access write only 

mechanism by reference 

Number of significant characters written to resultant-string by LIB$GETDVI. 
The resultant-length argument is the address of an unsigned word containing 
this length. 


Description 

LIB$GETDVI returns two categories of information. 

• Primary device characteristics 

• Secondary device characteristics 

LIB$GETDVI does not allow you to get more than one item of information in a 
single call. 
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LIB$GETDVI provides the following features in addition to those provided by the 
$GETDVI system service. 

• Instead of a list of item descriptors, which may be difficult to construct in 
high-level languages, the single item desired is specified as an integer code 
which is passed by reference. Results are written to separate arguments. 

• For items which return numeric values, LIB$GETDVI can optionally provide 
a formatted string interpretation of the value. For example, if the device 
owner UIC is requested, LIB$GETDVI can return the UIC formatted as 
[identifier]. 

• For string arguments, LIB$GETDVI understands all string classes supported 
by the Run-Time Library. 

• Calls to LIB$GETDVI are synchronous; LIB$GETDVI calls LIB$GET_EF to 
allocate a local event flag number for synchronization. 

See the description of the $GETDVI system service in the OpenVMS System 
Services Reference Manual for more detailed information. 

Item Codes 

All item codes that can be used with the $GETDVI system service may be used 
as the item-code argument to LIB$GETDVI. These codes have symbolic names 
beginning with DVI$_. 

The use of a DVI$_ code by itself will return the primary device characteristic 
associated with that code. To obtain the secondary device characteristics, add 1 
to the code. See the description of the $GETDVI system service for a list of the 
defined item codes. The symbolic names for these items are defined in Digital 
supplied symbol libraries in module $DVIDEF (where appropriate). 

Value Formats 

By using the longword-integer-value and resultant-string arguments to 
LIB$GETDVI, the information requested can be returned in two different 
fashions. 

• For those items described as “string” in the table of Item Identifier Codes for 
the $GETDVI service, the value is returned in resultant-string. 

• For all other items—those that have numeric values—the numeric 
representation is returned in longword-integer-value (if specified), and a 
formatted string interpretation of the value is returned in resultant-string. 

Each formatted item is written left-justified; resultant-length, if specified, gives 
the number of characters used. Table LIB—3 lists the formats used for the string 
interpretations. 
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Table LIB-3 Formats Used for LIB$GETDVI Strings 
Item or Format Description 


DVI$_ACPPID 

DVI$_PID 

DVI$_ACPTYPE 


DVI$_OWNUIC 


DVI$_VPROT 


Boolean 
All others 


The string value is returned as an 8-digit hexadecimal 
number. 

The string value is returned as an 8-digit hexadecimal 
number. 

The ACP type string is one of the following: 


NONE 

No ACP 

F11V1 

Files-11 Level 1 

F11V2 

Files—11 Level 2 

MTA 

Magnetic Tape 

NET 

Networks 

REM 

Remote I/O 


The standard UIC format [group,member] is used. If the 
format of a UIC includes identifiers from the access rights 
database in place of the octal group and member numbers, 
the UIC string returned will have these identifiers, if 
available. 

The volume protection string is in the following form: 

SYSTEM=RWLP,OWNER=RWLP,GROUP=RWLP,WORLD=RWLP 

If a category has no access, the equal sign is omitted. The 
string will not contain any embedded spaces. 

The value string returned is TRUE if the low bit of the 
value is set, or FALSE if the low bit is clear. 

The value string is returned in the form of an unsigned 
decimal integer. 


Condition Values Returned 

SS$_N ORMAL 
LIB$_STRTRU 

ss$_badparam 

SS$_IVDEVNAM 

LIB$_INSEF 

LIB$_INVARG 


Normal successful completion. 

String truncated. This is an alternate success 
return status. The fixed-length resultant-string 
argument could not contain all the characters of 
the returned item. 

Unrecognized item code. Item-code was not 
recognized as valid by $GETSYI. 

The device name string contains invalid 
characters, or neither the channel nor device¬ 
name arguments were specified. 

Insufficient event flags. A local event flag 
number could not be allocated by a call to 
LIB$GET_EF. 

Invalid arguments. The $GETSYI Item Identifier 
code describes the item as “string”, and no 
resultant-string argument was specified. 
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LIB$_INVSTRDES Invalid string descriptor. The descriptor of 

the resultant-string argument is not a valid 
descriptor. 

LIB$_WRONUMARG Wrong number of arguments. An incorrect 

number of arguments was passed to 
LIB$GETDVI. 

Any condition values returned by LIB$SCOPY_xxx. 

Any condition values returned by SYS$GETDVI. 
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LIB$GETJPI—Get Job/Process Information 

The Get Job/Process Information routine provides a simplified interface to the 
$GETJPI system service. It provides accounting, status, and identification 
information about a specified process. 

LIB$GETJPI obtains only one item of information in a single call. 

Format 

LIB$GETJPI item-code [,process-id] [,process-name] [,resultant-value] [,resultant-string] 

[,resultant-length] 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Arguments 

item-code 

OpenVMS usage longword_signed 
type longword (signed) 

access read only 

mechanism by reference 

Item identifier code specifying the item of information you are requesting. The 
item-code argument is the address of a signed longword containing the item 
code. You may request only one item in each call to LIB$GETJPI. 

LIB$GETJPI accepts all $GETJPI item codes. These names begin with JPI$_ and 
are defined in Digital supplied symbol libraries in module $JPIDEF. 

process-id 

OpenVMS usage processed 
type longword (unsigned) 

access modify 

mechanism by reference 

Process identifier of the process for which you are requesting information. The 
process-id argument is the address of an unsigned longword containing the 
process identifier. If you do not specify process-id, process-name is used. 

The process-id is updated to contain the process identifier actually used, 
which may be different from what you originally requested if you specified 
process-name or used wildcard process searching. 

process-name 

OpenVMS usage process_name 
type character string 

access read only 

mechanism by descriptor 
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A 1- to 15-character string specifying the name of the process for which you 
are requesting information. The process-name argument is the address of 
a descriptor pointing to the process name string. The name must correspond 
exactly to the name of the process for which you are requesting information; 
LIB$GETJPI does not allow trailing blanks or abbreviations. 

If you do not specify process-name, process-id is used. If you specify neither 
process-name nor process-id, the caller’s process is used. Also, if you do not 
specify process-name and you specify zero for process-id, the caller’s process 
is used. In this way, you can fetch the item you want and the caller’s PID in a 
single call to LIB$GETJPI. 

resultant-value 

OpenVMS usage varying_arg 
type unspecified 

access write only 

mechanism by reference 

Numeric value of the information you request. The resultant-value argument 
is the address of a longword or quadword into which LIB$GETJPI writes the 
numeric value of this information. Refer to Table LIB—4 for information on which 
items return longword values and which return quadword values. If the item you 
request returns only a string value, this argument is ignored. 

resultant-string 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor 

String representation of the information you request. The resultant-string 
argument is the address of a character string into which LIB$GETJPI writes the 
string representation. Table LIB-4 describes the string representation used for 
each item. 

If you do not include resultant-string, but the item you request has only a string 
representation, the error status LIB$_INVARG is returned. 

resultant-length 

OpenVMS usage word_unsigned 
type word (unsigned) 

access write only 

mechanism by reference 

Number of significant characters written to resultant-string by LIB$GETJPI. 
The resultant-length argument is the address of an unsigned word integer into 
which LIB$GETJPI writes the number of characters. 


Description 

LIB$GETJPI provides the following features in addition to those provided by the 
$GETJPI system service. 

• Instead of a list of item descriptors, which may be difficult to construct in 
high-level languages, the single item desired is specified as an integer code 
which is passed by reference. Results are written to separate arguments. 
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• For items which return numeric values, LIB$GETJPI can optionally provide a 
formatted string interpretation of the value. For example, if the process UIC 
is requested, LIB$GETJPI can return the UIC formatted as [g,m]. 

• For string arguments, all string classes supported by the Run-Time Library 
are understood. 

• Calls to LIB$GETJPI are synchronous. LIB$GETJPI calls LIB$GET_EF to 
allocate a local event flag number for synchronization. 

See the description of the $GETJPI system service in the OpenVMS System 
Services Reference Manual for more information. 

By using the resultant-value and resultant-string arguments to LIB$GETJPI, 
you can request that the information be returned in two ways. For those items 
described as “string” in the table of Item Identifier Codes for the $GETJPI service, 
the value is returned in resultant-string. For all other items—those which have 
numeric values—the numeric representation is returned in resultant-value 
(if specified), and a formatted string interpretation of the value is returned in 
resultant-string. 

Each formatted item is written left-justified; resultant-length, if specified, gives 
the number of characters used. For the items that return blank-padded strings 
(for example, JPI$_USERNAME) trailing blanks are removed. 

Table LIB-4 lists the formats used for the string interpretations. 


Table LIB-4 Item Code Formats for LIB$GETJPI 


Item or Format Description 


JPI$_AUTHPRIV 


JPI$_CURPRIV 

JPI$_IMAGPRIV 

JPI$_PROCPRIV 

JPI$_LOGINTIM 

JPI$_PID 

JPI$_STATE 


The string representation of these quadword privilege 
masks is a list of each privilege that is enabled. The 
privilege names are in uppercase, and are separated by 
commas. 

Same as for JPI$AUTHPRIV. 

Same as for JPI$AUTHPRIV. 

Same as for JPI$AUTHPRIV. 

The string representation of the quadword time is a 
standard absolute date-time string. 

The process identification string is an 8-digit 
hexadecimal number. 

The process state string is one of the following: 

CEF Common event flag wait 

COM Computable 

COMO Computable, outswapped 

(continued on next page) 
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Table LIB-4 (Cont.) Item Code Formats for LIB$GETJPI 


Item or Format 

Description 


CUR 

Current process 


COLPG 

Collided page wait 


FPG 

Free page wait 


HIB 

Hibernate wait 


HIBO 

Hibernate wait, outswapped 


LEF 

Local event flag wait 


LEFO 

Local event flag wait, outswapped 


MWAIT 

Mutex and miscellaneous resource wait 


PFW 

Page fault wait 


SUSP 

Suspended 


SUSPO 

Suspended, outswapped 

JPI$_UIC 

The standard UIC format [group,member] is used. If 
the format of a UIC includes identifiers from the access 
rights database in place of the octal group and member 
numbers, the UIC string returned will have these 
identifiers, if available. 

JPI$_MODE 

The current mode string is one of the following: BATCH, 
INTERACTIVE or NETWORK. 

All others 

The string value is returned as an unsigned decimal 
integer. 


Condition Values Returned 


SS$_N ORMAL 
LIB$_STRTRU 

SS$_BADPARAM 

LIB$_INSEF 

LIB$_INVARG 

LIB $_INV STRDE S 
LIB$_WRONUMARG 


Normal successful completion. 

String truncated. This is an alternate success 
return status. The fixed-length resultant-string 
argument could not contain all the characters of 
the returned item. 

Unrecognized item code. Item-code was not 
recognized as valid by $GETJPI. 

Insufficient event flags. A local event flag 
number could not be allocated by a call to 
LIB$GET_EF. 

Invalid arguments. The $GETSYI Item Identifier 
code describes the item as “string”, and no 
resultant-string argument was specified. 

Invalid string descriptor. The descriptor for a 
string argument was not a valid string descriptor. 

Wrong number of arguments. An incorrect 
number of arguments was passed to 
LIB$GETJPI. 


Any condition value returned by LIB$SCOPY_xxx. 
Any condition value returned by SYS$GETJPI. 
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LIB$GETQUI—Get Queue Information 

The Get Queue Information routine provides a simplified interface to the 
$GETQUI system service. It provides queue, job, file, characteristic, and form 
information about a specified process. 

LIB$GETQUI obtains only one item of information in a single call. 

Format 

LIB$GETQUI function-code [,item-code] [,search-number] [,search-name] [,search-flags] [,resultant-value] 
[,resultant-string] [,resultant-length] 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Arguments 

function-code 

OpenVMS usage longword_signed 
type longword (signed) 

access read only 

mechanism by reference 

Function code specifying the function that LIB$GETQUI is to perform. The 
function-code argument is the address of a signed longword containing the 
function code. 

LIB$GETQUI accepts all $GETQUI function codes. These names begin with 
QUI$_ and are defined in Digital supplied symbol libraries in module $QUIDEF. 

item-code 

OpenVMS usage longword_signed 
type longword (signed) 

access read only 

mechanism by reference 

Item identifier code specifying the item of information you are requesting. The 
item-code argument is the address of a signed longword containing the item 
code. You may request only one item in each call to LIB$GETQUI. 

LIB$GETQUI accepts all $GETQUI item codes. These names begin with QUI$_ 
and are defined in Digital supplied symbol libraries in module $QUIDEF. 

search-number 

OpenVMS usage longword_signed 
type longword integer (signed) 

access read only 

mechanism by reference 


cond_value 
longword (unsigned) 
write only 
by value 
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Numeric value used to process your request. The search-number argument 
is the address of a signed longword integer containing the number needed to 
process your request. Search-number directly corresponds to QUI$_SEARCH_ 
NUMBER as described by the $GETQUI system service. 

search-name 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Character string used to process your request. The search-name argument 
is the address of a string descriptor that provides the name needed to process 
your request. Search-name directly corresponds to QUI$_SEARCH_NAME as 
described by the $GETQUI system service. 

search-flags 

OpenVMS usage longword_unsigned 
type longword integer (unsigned) 

access read only 

mechanism by reference 

Optional bit mask indicating request to be performed. The search-flags 
argument is the address of an unsigned longword integer containing the bit 
mask. Search-flags directly corresponds to $QUI_SEARCH_FLAGS as described 
by the $GETQUI system service. 

resultant-value 

OpenVMS usage varying_arg 
type unspecified 

access write only 

mechanism by reference 

Numeric value of the information you requested. The resultant-value argument 
is the address of a longword, quadword or octaword into which LIB$GETQUI 
writes the numeric value of this information. Refer to Table LIB—5 for 
information on which items return values other than longwords. If the item 
you requested returns only a string value, this argument is ignored. 

resultant-string 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor 

String representation of the information you requested. The resultant-string 
argument is the address of a character string into which LIB$GETQUI writes the 
string representation. Table LIB—5 describes the string representation used for 
each item. 

If you do not include resultant-string, but the item you request has only a string 
representation, the error status LIB$_INVARG is returned. 
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resultant-length 

OpenVMS usage word_signed 
type word integer (signed) 

access write only 

mechanism by reference 

Number of significant characters written to resultant-string by LIB$GETQUI. 
The resultant-length argument is the address of a signed word integer into 
which LIB$GETQUI writes the number of characters. 


Description 

LIB$GETQUI provides a simplified interface to the $GETQUI system service. It 
provides queue, job, file, characteristic, and form information about a specified 
process. This routine obtains only one item of information in a single call. 

LIB$GETQUI provides the following features in addition to those provided by the 
$GETQUI system service. 

• Instead of a list of item descriptors that may be difficult to construct in high- 
level languages, the single item desired is specified as an integer code which 
is passed by reference. Results are written to separate arguments. 

• For items that return numeric values, LIB$GETQUI optionally can provide a 
formatted string interpretation of the value. For example, if you request the 
characteristics of a queue, LIB$GETQUI can return the list of characteristics 
as “23,42,76,98,125”. 

• For string arguments, all string classes supported by the Run-Time Library 
are understood. 

• Calls to LIB$GETQUI are synchronous. LIB$GETQUI calls $GETQUIW to 
force the synchronization. 

LIB$GETQUI retains context. This means that previous calls to LIB$GETQUI 
affect current calls to LIB$GETQUI. 

See the description of the $GETQUI system service in the OpenVMS System 
Services Reference Manual for more information. 

By using the resultant-value and resultant-string arguments to LIB$GETQUI, 
you can request that the information be returned in two ways. For items that 
have numeric values, the numeric representation is returned in resultant-value 
(if specified), and a formatted string interpretation of the value is returned in 
resultant-string. For those items described as “string” in the table of Item 
Identifier Codes for the $GETQUI service, the value is returned in resultant¬ 
string. 

Each formatted item is written left-justified; resultant-length, if specified, gives 
the number of characters used. For the items that return blank-padded strings, 
trailing blanks are removed. 

The $GETQUI system service requires some item codes. LIB$GETQUI provides 
those item codes for you by corresponding your input to LIB$GETQUI directly to 
the required input codes. 

The following table describes all of the required and optional input needed to 
perform your task with LIB$GETQUI. 


LIB-227 



LIB$GETQUI 


Function 

Input Description 

QUI$_CANCEL 

Accepts no input. 

QUI$_DISPLAY_CHARACTERISTIC 

A characteristic name or number, 
or both. Optionally, a search flags 
number. 

qui$_display_entry 

Optionally, an entry number, user 
name, and search flags number. The 
default user name is that of the calling 


process. 

QUI$_DISPLAY_FILE 

Optionally, a search flags number. 

QUI$_DISPLAY_FORM 

A form name or number, or both. 
Optionally, a search flags number. 

QUI$_DISPLAY_JOB 

Optionally, a search flags number. 

QUI$_DISPLAY_QUEUE 

A queue name. Optionally, a search 
flags number. 

QUI$_TRAN SLATE_QUEUE 

A queue name. 

Table LIB—5 lists the formats used for the string interpretations. 

Table LIB-5 Item Code Formats for LIB$GETQUI 

Item or Format 

Description 

QUI$_AFTER_TIME 

Returns a quadword resultant-value as 
well as a resultant-string. 

QUI$_CHARACTERISTICS 

Returns an octaword resultant-value as 
well as a comma-separated list that lists 
all the characteristic numbers, output as 

a resultant-string. 

QUI$_SUBMISSION_TIME 

Returns a quadword resultant-value as 
well as a resultant-string. 

QUI$_UIC 

Returns a formatted resultant-string as 
well as a longword. 


Condition Values Returned 

SS$_NORMAL 

LIB$_STRTRU 

S S $_B AD PAR AM 
LIB$_INSEF 


Routine successfully completed. 

String truncated. This is an alternate success 
return status. The fixed-length resultant-string 
argument could not contain all the characters of 
the returned item. 

Unrecognized item code. Item-code was not 
recognized as valid by $GETQUI. 

Insufficient event flags. A local event flag 
number could not be allocated by a call to 
LIB$GET_EF. 
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LIB$_INVARG Invalid arguments. The $GETSYI Item Identifier 

code describes the item as “string”, and no 
resultant-string argument was specified. 

LIB$_INVSTRDES Invalid string descriptor. The descriptor for a 

string argument was not a valid string descriptor. 

LIB$_WRONUMARG Wrong number of arguments. An incorrect 

number of arguments was passed to 
LIB$GETQUI. 

Any condition value returned by LIB$SCOPY_xxx. 

Any condition value returned by SYS$GETQUI. 
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LIB$GETSYI—Get Systemwide Information 

The Get Systemwide Information routine provides a simplified interface to the 
$GETSYI system service. The $GETSYI system service obtains status and 
identification information about the system. LIB$GETSYI returns only one item 
of information in a single call. 

Format 

LIB$GETSYI item-code [,resultant-value] [,resultant-string] [,resultant-length] [,cluster-system-id] 

[,node-name] 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Arguments 

item-code 

OpenVMS usage longword_signed 
type longword (signed) 

access read only 

mechanism by reference 

Item code specifying the desired item of information. The item-code argument 
is the address of a signed longword containing this item code. All valid $GETSYI 
item codes are accepted. 

resultant-value 

OpenVMS usage varying_arg 
type unspecified 

access write only 

mechanism by reference 

Numeric value returned by LIB$GETSYI. The resultant-value argument is the 
address of a longword or quadword containing this value. If an item is listed as 
returning only a string value, this argument is ignored. 

resultant-string 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor 

Information returned by LIB$GETSYI. The resultant-string argument is the 
address of a descriptor pointing to the character string that will receive this 
information. 

See the Description section for more information about value formats. If 
resultant-string is not specified and if the returned value has only a string 
representation, the error status LIB$_INVARG is returned. 
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resultant-length 

OpenVMS usage word_unsigned 
type word (unsigned) 

access write only 

mechanism by reference 

Number of significant characters written to resultant-string, not including 
blank padding or truncated characters. The resultant-length argument is the 
address of an unsigned word into which LIB$GETSYI returns this number. 

cluster-system-id 

OpenVMS usage identifier 
type longword (unsigned) 

access modify 

mechanism by reference 

Cluster system identification (CSID) of the node for which information is to 
be returned. The cluster-system-id argument is the address of this CSID. 

If cluster-system-id is specified and is nonzero, node-name is not used. If 
cluster-system-id is specified as zero, LIB$GETSYI uses node-name and 
writes into the cluster-system-id argument the CSID corresponding to the node 
identified by node-name. 

The cluster-system-id of an OpenVMS node is assigned by the cluster- 
connection software and may be obtained by the DCL command SHOW 
CLUSTER. The value of the cluster-system-id for an OpenVMS node is not 
permanent; a new value is assigned to an OpenVMS node whenever it joins or 
rejoins the VAXcluster. 

If cluster-system-id is specified as —1, LIB$GETSYI assumes a wildcard 
operation and returns the requested information for each OpenVMS node in the 
cluster, one node per call. 

If cluster-system-id is not specified, node-name is used, 

node-name 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Name of the node for which information is to be returned. The node-name 
argument is the address of a descriptor pointing to the node name string. If 
cluster-system-id is not specified or is specified as zero, node-name is used. If 
neither node-name nor cluster-system-id is specified, the caller’s node is used. 
See the cluster-system-id argument for more information. 

The node name string must contain from 1 to 15 characters and must correspond 
exactly to the OpenVMS node name; no trailing blanks nor abbreviations are 
permitted. 
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Description 

LIB$GETSYI provides the following features in addition to those provided by the 
$GETSYI system service: 

• Instead of a list of item descriptors, which may be difficult to construct in 
high-level languages, the single item desired is specified as an integer code 
which is passed by reference. Results are written to separate arguments. 

• For items which return numeric values, LIB$GETSYI can optionally provide 
a formatted string interpretation of the value. 

• For string arguments, all string classes supported by the Run-Time Library 
are understood. 

• Calls to LIB$GETSYI are synchronous. LIB$GETSYI calls LIB$GET_EF to 
allocate a local event flag number for synchronization. 

All item codes that can be used with the $GETSYI system service may be used 
as the item-code argument to LIB$GETSYI. See the description of the $GETSYI 
system service for a list of the defined item codes. Note that the symbolic 
names for these items are defined in Digital supplied symbol libraries in module 
$SYIDEF (where appropriate). 

Value Formats 

By using the resultant-value and resultant-string arguments to LIB$GETSYI, 
you can request that the information be returned in two ways. For those items 
described as “string” in the table of Item Identifier Codes for the $GETSYI 
service, the value is returned in resultant-string. For all other items— 
those which have numeric values—the numeric representation is returned in 
resultant-value (if specified), and an unsigned decimal integer representation is 
stored in resultant-string. 

Each formatted item is written left-justified; resultant-length, if specified, gives 
the number of characters used. For those items which return blank-padded 
strings, such as SYI$_VERSION, trailing blanks are removed. 

See the OpenVMS System Services Reference Manual for a description of the 
$GETSYI system service. 


Condition Values Returned 

SS$_N ORMAL 
LIB$_STRTRU 


SS$_BADPARAM 

LIB$_INSEF 

LIB$_INVARG 


Normal successful completion. 

String truncated. This is an alternate success 
return status. The fixed-length resultant-string 
argument could not contain all the characters of 
the returned item. 

Unrecognized item code. Item-code was not 
recognized as valid by $GETSYI. 

Insufficient event flags. A local event flag 
number could not be allocated by a call to 
LIB$GET_EF. 

Invalid arguments. The $GETSYI item identifier 
code describes the item as “string”, and no 
resultant-string argument was specified. 
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LIB$_INVSTRDES Invalid string descriptor. The descriptor of 

the resultant-string argument is not a valid 
descriptor. 

LIB$_WRONUMARG Wrong number of arguments. An incorrect 

number of arguments was passed to 
LIB$GETSYI. 

Any condition values returned by LIB$SCOPY_xxx. 

Any condition values returned by the $GETSYI system service. 


LIB-233 



LIB$ICHAR 


LIBSICHAR—Convert First Character of String to Integer 

The Convert First Character of String to Integer routine converts the first 
character of a source string to an 8-bit ASCII integer extended to a longword. 


Format 

LIB$ICHAR source-string 

Returns 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access write only 

mechanism by value 

First character of the source string. This character is returned by LIB$ICHAR as 
an 8-bit ASCII value extended to a longword. If the source string has zero length, 
LIB$ICHAR returns a zero. 

Argument 

source-string 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Source string whose first character is converted to an integer by LIB$ICHAR. The 
scr-str argument is the address of a descriptor pointing to this source string. 


Description 

Although FORTRAN users can call LIB$ICHAR, it is more efficient to use the 
FORTRAN intrinsic function ICHAR, which generates equivalent code in line. 

Condition Values Returned 

None. 


Example 


PROGRAM ICHAR(INPUT, OUTPUT); 

{ + } 

{ This program demonstrates how to call LIB$ICHAR 
{ to convert the first character of string to an 
{ integer value. 

{-} 

FUNCTION LIB$ICHAR(SRCSTR : VARYING [A] OF CHAR) : INTEGER; 
EXTERN; 

{ + } 

{ Declare the variables to be used. 

{-} 

VAR 

CHARSTR : VARYING [256] OF CHAR; 

RET_STATUS : INTEGER; 
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{+} 

{ Begin the main program. Read the character string, 

{ call LIBN$ICHAR, and print the result. 

{-} 

BEGIN 

WRITELN('Enter string: '); 

READLN(CHARSTR); 

RET_STATUS := LIB$ICHAR(CHARSTR); 

WRITELN(RET_STATUS); 

END. 

The output generated by this Pascal program is as follows: 

$ RUN ICHAR 
Enter string: 

Pencil sharpener 

80 

$ RUN ICHAR 
Enter string: 
pencil sharpener 
112 

Notice that this routine changes any uppercase characters to lowercase. 
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LIBSINDEX—Index to Relative Position of Substring 

The Index to Relative Position of Substring routine returns an index, which is the 
relative position of the first occurrence of a substring in the source string. 


Format 

LIBSINDEX source-string ,sub-string 


Returns 


OpenVMS usage longword_unsigned 
type longword (unsigned) 

access write only 

mechanism by value 

The relative position of the first character of the substring if found, or zero if not 
found. 


Arguments 

source-string 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Source string to be searched by LIB$INDEX. The source-string argument is the 
address of a descriptor pointing to this source string. 

sub-string 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Substring to be found. The sub-string argument is the address of a descriptor 
pointing to this substring. 


Description 

The relative character positions returned by LIB$INDEX are numbered 1, 2, ..., 
n. Thus, zero means that the substring was not found. 

If the substring has a zero length, LIB$INDEX returns the value 1, indicating 
success, no matter how long the source string is. If the source string has a zero 
length and the substring has a nonzero length, zero is returned, indicating that 
the substring was not found. 

FORTRAN users may use the built-in INDEX function rather than calling 
LIB$INDEX directly. 
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Condition Values Returned 

None. 
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LIB$INIT_DATE_TIME_CONTEXT—Initialize the Context Area Used in 

Formatting Dates and Times for 
Input or Output 

The Initialize the Context Area Used in Formatting Dates and Times for 
Input or Output routine allows the user to initialize the context area used by 
LIB$FORMAT_DATE_TIME or LIB $ C ONVE RT_D ATE_STRIN G with specific 
strings, instead of through logical name translation. 

Format 

UB$INIT_DATE_TIME_CONTEXT user-context .component ,init-string 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Arguments 

user-context 

OpenVMS usage context 
type longword (unsigned) 

access modify 

mechanism by reference 

User context that retains the translation context over multiple calls to this 
routine. The user-context argument is the address of an unsigned longword 
that contains this context. The initial value of the context variable must be zero. 
Thereafter, the user program must not write to the cell. 

component 

OpenVMS usage longword_signed 
type longword (signed) 

access read only 

mechanism by reference 

The component of the context that is being initialized. The component argument 
is the address of a signed longword that indicates this component. Only one 
component can be initialized per call to LIB$INIT_DATE_TIME; these component 
codes are shown in the following list. 

• LIB$K_MONTH_NAME 

• LIB$K_MONTH_NAME_ABB 

• LIB$K_FORMAT_MNEMONICS 

• LIB$K_WEEKDAY_NAME 

• LIB$K_WEEKDAY_NAME_ABB 

• LIB$K_RELATIVE_DAY_NAME 


cond_value 
longword (unsigned) 
write only 
by value 


LIB-238 




LIB$INIT_DATE_TIME_CONTEXT 


• LIB$K_MERIDIEM_INDICATOR 

• LIB$K_OUTPUT_FORMAT 

• LIB$K_INPUT_FORMAT 

• LIB$K_LANGUAGE 

init-string 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

The characters which are to be used in formatting dates and times for input or 
output. The init-string argument is the address of a descriptor pointing to this 
string. 


Description 

The LIB$INIT_DATE_TIME_CONTEXT routine allows the user to initialize the 
context area used by either LIB$CONVERT_DATE_STRING or LIB$FORMAT_ 
DATE_TIME with specific strings instead of through logical name translations. 
This routine is therefore useful when the application is formatting either input 
or output strings that are used only by other computer applications and are not 
intended for presentation to users. 

When the text will be parsed by another program, you must specify all of the 
context (including spellings). For applications where the context specifies a user’s 
preferred format style, spellings can be looked up from the logical name tables. 

Therefore, when the text will be parsed by another program, the minimum effort 
required to initialize the necessary format strings would be a call to LIB$INIT_ 
DATE_TIME_CONTEXT specifying the input or output format strings to be 
used. If the specified format requires spelled items, such as month names or day 
names, then additional calls to LIB$INIT_DATE_TIME_CONTEXT are required 
to provide the spellings of these items. Applications where the context specifies a 
user’s preferred format style can specify only the language name, and allow the 
strings to be looked up from logical name tables. 

The format of the strings used by this routine is as follows: 

"[delim][string-l][delim] [string-2][delim] . . . [delim][string-n][delim]" 

In this format, [delim] is any character that is not in any of the strings, and 
[string-x] is the spelling of that instance of the component. 

For example, a string passed to this routine to specify the English spellings of the 
month names might be as follows: 

I JAN I FEB I MAR I APR I MAY I JUN 
I JUL I AUG I SEP I OCT I NOV I DEC I " 

Note that the string starts and ends with a delimiter. Thus, there is one more 
delimiter than there are string elements. Each type of component has a natural 
number of elements associated. The string must contain exactly that number of 
elements. 
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Month names (full or abbreviated) 12 

Format mnemonics 9 

Day names (full or abbreviated) 7 

Relative day names 3 

Meridiem indicators 2 

Output format strings 2 

Input format string 1 

Language 1 


In order to specify the input format mnemonics using LIB$INIT_DATE_ 
TIME_CONTEXT, the user must initialize the component LIB$K_FORMAT_ 
MNEMONICS with the appropriate values. The following table lists in order the 
9 fields that must be initialized, along with their default (English) values. 


Order 

Format Field 

Legible Mnemonic (Defaults) 

1 

Year 

YYYY 

2 

Numeric month 

MM 

3 

Numeric day 

DD 

4 

Hours (12- or 24-hour) 

HH 

5 

Minutes 

MM 

6 

Seconds 

SS 

7 

Fractional seconds 

cc 

8 

Meridiem indicator 

AM/PM 

9 

Alphabetic month 

MONTH 


For example, the following would be a valid definition of LIB$K_FORMAT_ 
MNEMONICS using Austrian as the natural language: 

|JJJJ|MM|TT|SS|MM|SS|HH| |MONAT| 

To specify an output format using LIB$INIT_DATE_TIME_CONTEXT, the user 
must initialize the variable LIB$K_OUTPUT_FORMAT. There are two elements 
associated with this output format string. One describes the date format fields, 
the other the time format fields. The order in which they appear in the string 
determines the order in which they are output. A single space is inserted into 
the output stream between the two elements, if the call to LIB$FORMAT_DATE. 
TIME specifies that both be output. In the following example, the two elements 
associated with the output format string are delimited by vertical bars. 

I !DB-!MAAU-!Y4 I !H04:!M0:!S0.!C2 I " 

This output format string represents the format used by the $ASCTIM system 
service for outputting times. Note that the middle delimiter is replaced by a 
space in the resultant output. 

A more detailed description of the format mnemonics used in these routines is 
given in the introductory section of this manual. 
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Condition Values Returned 


SS$_N ORMAL 

LIB$_NUMELEMENTS 

LIB$_ILLINISTR 

LIB$_UNRFORCOD 

LIB$_ILLCOMPONENT 


Normal successful completion. 

Incorrect number of elements for the component. 
Illegally formed init-string. 

Unrecognized format code. 

Illegal value for the component. 


Any condition value returned by LIB$GET_VM. 

Any condition value returned by LIB$ANALYZE_SDESC. 
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LIB$INIT_TIMER—Initialize Times and Counts 

The Initialize Times and Counts routine stores the current values of specified 
times and counts for use by LIB$SHOW_TIMER or LIB$STAT_TIMER. 


Format 

LIB$INIT_TIMER [context] 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Argument 


context 

OpenVMS usage 

type 

access 

mechanism 


context 

longword (unsigned) 

modify 

by reference 


Context variable that retains the values of the times and counts. The context 
argument contains the address of an unsigned longword that is this context. 
When you call LIB$INIT_TIMER, you must use the optional context argument 
only if you want to maintain several sets of statistics simultaneously. 


• If context is omitted, the control block is allocated in static storage. This 
method is not AST reentrant. 


• If context is zero, a control block is allocated in dynamic heap storage. The 
times and counts will be stored in that block and the address of the block 
returned in context. This method is fully reentrant and modular. 

• If context is nonzero, it is considered to be the address of a control block 
previously allocated by a call to LIB$INIT_TIMER. If so, the control block is 
reused, and fresh times and counts are stored in it. 

When LIB$INIT_TIMER returns, the block of storage referred to by context will 
contain the times and counts. 


Description 

LIB$INIT_TIMER stores the current values of specified times and counts in one 
of three places, depending on the value of the optional context argument. 

You need to call LIB$FREE_TIMER only if you have specified context in 
LIB$INIT_TIMER and you wish to deallocate all heap storage resources. 
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Condition Values Returned 

SS$_N ORMAL 
LIB$_INVARG 

LIB$_IN SVIRMEM 


Routine successfully completed. 

Invalid argument; context is nonzero and the 
block to which it refers was not initialized on a 
previous call to LIB$INIT_TIMER. 

Context is zero, and there is insufficient virtual 
memory to allocate a storage block. 
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LIB$INSERT_TREE—Insert Entry In a Balanced Binary Tree 

The Insert Entry in a Balanced Binary Tree routine inserts a node in a balanced 
binary tree. 

Format 

LIB$INSERT_TREE treehead .symbol .flags ,user-compare-routine ,user-allocation-procedure ,new-node 
[.user-data] 

Returns 

OpenVMS usage cond_value 
type longword (signed) 

access write only 

mechanism by value 

Arguments 

treehead 

OpenVMS usage address 
type address 

access modify 

mechanism by reference 

Tree head for the binary tree. The treehead argument is the address of a 
longword that is this tree head. The initial value of treehead is 0. 

symbol 

OpenVMS usage 
type 
access 
mechanism 

Key to be inserted. 

flags 

OpenVMS usage maskjongword 
type longword (unsigned) 

access read only 

mechanism by reference 

Control flags. The flags argument is the address of the control flags. Currently 
only bit zero is used. 

Bit Description 

0 If clear, the address of the existing duplicate entry is returned to the 

new-node argument. If set, duplicate entries are inserted. 

user-compare-routine 

OpenVMS usage procedure 
type procedure value 

access function call (before return) 

mechanism by value 


user_arg 

longword (unsigned) 

unspecified 

unspecified 
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User-supplied compare routine that LIB$INSERT_TREE calls to compare 
a symbol with a node. The user-compare-routine argument is required; 
LIB$INSERT_TREE calls the compare routine for every node except the first 
node in the tree. The value returned by the compare routine indicates the 
relationship between the symbol key and the node. 

For more information on the compare routine, see “Call Format for a Compare 
Routine” in the Description section below. 

user-allocation-procedure 

OpenVMS usage procedure 
type procedure value 

access function call (before return) 

mechanism by value 

User-supplied allocate routine that LIB$INSERT_TREE calls to allocate virtual 
memory for a node. The user-allocation-procedure argument is required; 
LIB$INSERT_TREE always calls the allocate routine. 

For more information on the allocate routine, see “Call Format for an Allocate 
Routine” in the Description section below. 

new-node 

OpenVMS usage address 
type longword (unsigned) 

access write only 

mechanism by reference 

Location where the new key is inserted. The new-node argument is the address 
of an unsigned longword that is the address of the new node. 

user-data 

OpenVMS usage user_arg 
type unspecified 

access unspecified 

mechanism by value 

User data that LIB$INSERT_TREE passes to the compare and allocate routines. 
User-data is an optional argument. 


Description 

This Description section contains three parts. 

• Guidelines for using LIB$INSERT_TREE 

• Call format for a compare routine 

• Call format for an allocate routine 

Guidelines for Using LIB$INSERT_TREE 

LIB$INSERT_TREE inserts a node in a balanced binary tree. You supply two 
routines: compare and allocate. The compare routine compares the symbol key 
to the node, and the allocate routine allocates virtual memory for the node to be 
inserted. LIB$INSERT_TREE first calls the compare routine to find the location 
at which the new node is inserted. Then LIB$INSERT_TREE calls the allocate 
routine to allocate memory for the new node. Most programmers insert data in 
the new node by initializing it within the allocate routine as soon as memory has 
been allocated. 


LIB-245 



LIB$INSERT_TREE 


You may pass the data to be inserted into the tree using either the symbol 
argument alone or both the symbol and user-data arguments. The symbol 
argument is required. It may contain all of the data, just the name of the node, 
or the address of the data. If you decide to use symbol to pass just the name of 
the node, you must use the user-arg argument to pass the rest of the data to be 
inserted in the new node. 

Call Format for a Compare Routine 

The call format of a compare routine is as follows: 

user-compare-routine symbol,comparison-node [,user-data] 

LIB$INSERT_TREE passes both the symbol and comparison-node arguments 
to the compare routine, using the same passing mechanism that was used to pass 
them to LIB$INSERT_TREE. The user-data argument is passed in the same 
way, but its use is optional. 

The user-compare-routine argument in the call to LIB$INSERT_TREE 
specifies the compare routine. This argument is required. LIB$INSERT_TREE 
calls the compare routine for every node except the first node in the tree. 

The value returned by the compare routine is the result of comparing the symbol 
key with the current node. Listed below are the possible values returned by the 
compare routine. 


Value 

Description 

Negative 

Zero 

Positive 

symbol is less than the current node 
symbol is equal to the current node 
symbol is greater than the current node 


This is an example of a user-supplied compare routine written in BASIC. 


FUNCTION LONG Compare_node ( & 

STRING Key_string, & 

Node_type Node, & 

LONG Dummy) 

+ 

This function compares the string described by Key_string with 
the string contained in the data node Node, and returns 0 
if the strings are equal, -1 if Key_string is < Node, and 
1 if Key_string > Node. 


OPTION TYPE = EXPLICIT 
RECORD Node_type 

BYTE Header (9) I Header 

BYTE Length ! Length 

STRING Text =80 ! String 

END RECORD Node_type 

DECLARE STRING Node_string 

! + 

! Return the result of the comparison. 

i _ 

Node_string = SEG$ (Node::Text, 1, Node::Length) 
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SELECT Key_string 


CASE < Node string 


Compare node = 

-1% 

CASE > Node string 


Compare node = 

1% 

CASE ELSE 


Compare node = 

0% 


END SELECT 
END FUNCTION 

Call Format for an Allocate Routine 

LIB$INSERT_TREE calls the allocate routine to allocate virtual memory for a 
node. The allocate routine then stores the value of user-data in the field of the 
allocated node. 

The format of the call is as follows: 
user-allocation-procedure symbol ,new-node [,user-data] 

LIB$INSERT_TREE passes the symbol, new-node, and user-data arguments 
to your allocate routine, using the same passing mechanisms that were used to 
pass them to LIB$INSERT_TREE. Use of user data is optional. 

A node header appears at the beginning of each node. The following figure shows 
the structure of a node header. 



Therefore, any node you declare that LIB$INSERT_TREE manipulates must 
contain 10 bytes of reserved data at the beginning for the node header. 

How a node is structured depends on how you allocate your user data. You can 
allocate data in one of two ways: 

1. Your data immediately follows the node header. In this case your allocation 
routine must allocate a block equal in size to the sum of your data plus 10 
bytes for the node header. 



(4 Bytes) 
(4 Bytes) 
(2 Bytes) 
(Variable) 


ZK-1927-GE 
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2. The node contains the 10 bytes of header information and a longword pointer 
to the user data. 


(4 Bytes) 
(4 Bytes) 
(4 Bytes) 
(2 Bytes) 


ZK-1928-GE 

The user-allocation-procedure argument in the call to LIB$INSERT_TREE 
specifies the allocate routine. This argument is required. LIB$INSERT_TREE 
always calls the allocate routine. 

This is an example of a user-supplied allocate routine written in BASIC. 

FUNCTION LONG Alloc_node ( & 

STRING Key_string, & 

LONG Ret_addr, & 

LONG Dummy) 

! + 

! Allocate virtual memory for a new node. KEY_STRING 
! is a descriptor of the string to enter into the newly 

! allocated node. RET_ADDR will contain the address 

! of the allocated memory. 


OPTION TYPE = EXPLICIT 
DECLARE LONG Status_code 
EXTERNAL LONG FUNCTION LIB$GET_VM 
EXTERNAL SUB LIB$M0VC3 

1 + 

! Allocate node: 10 for header, 1 for length plus length of string 

I _ 

Status_code = LIB$GET_VM (10% + LEN (Key_string) + 1%, Ret_addr) 
EXIT FUNCTION Status_code IF (Status_code AND 1%) <> 1% 

! + 

! Store key string length in byte 11 of node. Note that LIB$M0VC3 
! accepts its arguments by reference. If unable to allocate, pass 
! an even value to indicate failure. 

i _ 

CALL LIB$MOVC3 (1%, LEN (Key_string), (Ret_addr + 10%) BY VALUE) 

! + 

! Store key string in bytes 12:n of node. 

i _ 

CALL LIB$MOVC3 (LEN (Key_string), Key_string BY REF, & 

(Ret_addr + 11%) BY VALUE) 

Alloc_node =1% 

END FUNCTION 
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Condition Values Returned 


LIB$_NORMAL 
LIB $_KE YALRIN S 

LIB$_INSVIRMEM 


Routine successfully completed. 

Routine successfully completed, but a key was 
found in the tree. A new key was not inserted. 

Insufficient virtual memory. A call to LIB$GET_ 
VM has failed because your program’s virtual 
memory requirements have exceeded either your 
process quota (PGFLQUOTA) or the system 
parameter VIRTUALPAGCNT. 


Any other failure status reported by the user allocation procedure. 


Example 


1 %TITLE 'LIB$ Tree Example In BASIC' 

%SBTTL 'Main Program' 

! + 

! This program will ask the user to enter a series of strings, 

! one per line. The user will them be permitted to query the 

! program to find strings that were previously entered. At the 

! end, the entire tree will be displayed, along with the sequence 
! number that indicates the order in which the element was entered. 

i 

! This program should serve as an example of the use of LIB$INSERT_TREE, 
! LIB$LOOKUP_TREE and LIB$TRAVERSE_TREE. 


OPTION TYPE = EXPLICIT ! Everything must be declared 

DECLARE INTEGER CONSTANT True = -1 ! Useful named constant 


COMMON STRING Text_line =80 
DECLARE LONG 

Tree_head 
,New_node 
,Status_code 
,Counter 

RECORD Tree_element 
LONG Seq_num 

LONG Text_len 

STRING Text =80 
END RECORD Tree element 


! Allocate static line buffer 

! Some variables & 

! Head for the tree & 

! New node after insert & 

! Return status code & 

! Sequence number 

! Define the structure of our 
! record. This record could 
! contain many useful data items 


DECLARE Tree element Rec 


Declare an instance of the record 


EXTERNAL LONG FUNCTION LIB$INSERT_TREE 
EXTERNAL SUB LIB$TRAVERSE_TREE 
EXTERNAL LONG FUNCTION LIB$LOOKUP_TREE 
EXTERNAL SUB LIB$STOP 


I Function to insert node 
! Routine to walk tree 
! Routine to find a node 
! Routine to signal fatal error 


EXTERNAL LONG 

Compare_node_2 
,Compare_node_3 
,Alloc_node 
,Print_node 


! Routine entry points 
! Compare entry (2 arg) 
! Compare entry (3 arg) 
! Allocation entry 
! Print entry for walk 


EXTERNAL LONG CONSTANT LIB$ KEYNOTFOU 


! Key not found 


& 

& 

& 

& 
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! + 

! Initialize the tree to null and open the terminal for I/O. 

i _ 

Tree_head =0% 

OPEN 'SYS$INPUT / AS FILE #1 


10 


PRINT 'Enter one word per line, A Z to begin searching the tree' 

ON ERROR GOTO Input_EOF ! Establish error handler 

! + 

I Loop, reading lines of text until the end of the file. 


Counter = 0 
WHILE True 

LINPUT #1, '> '; Text_line 

Counter = Counter + 1 

Rec::Seq_Num = Counter 

Rec::Text_len = LEN(TRM$(Text_line)) 

Rec::Text = TRM$(Text_line) 

Status_code = LIB$INSERT_TREE ( ! Insert entry into the tree & 

Tree_head, Rec, 1%, & 

Compare_node_3, Alloc_node, New_node) 

CALL LIB$STOP (Status_code BY VALUE) IF (Status_code AND 1%) <> 1% 

NEXT 
20 ! + 

! End of file encountered. Begin searching the tree. 

i _ 

PRINT 

PRINT "You will now be prompted for words to find. Enter one per line." 
Rec::Seq_num = -1% 

WHILE True 
PRINT 

LINPUT #1%, 'Word to find? '; Text_line 
Rec::Text_len = LEN(TRM$(Text_line)) 

Rec::Text = TRM$(Text_line) 

Status_code = LIB$LOOKUP_TREE (Tree_head, Rec, Compare_Node_2, New_node) 

IF Status_code = LIB$_KEYNOTFOU 

THEN 

PRINT "The word you entered does not appear in the tree" 

ELSE 

CALL Display_Node (New_node BY VALUE) 

END IF 

NEXT 


+ 

The user has finished searching the tree for specific items. It 
is now time to traverse the entire tree. 


PRINT 

PRINT "The following is a dump of the tree. Notice that the words" 
PRINT "are in alphabetical order" 

CALL LIB$TRAVERSE_TREE (Tree_head, Print_node, 0% BY VALUE) 

GOTO End_of_program 

Input_EOF: 
i + 

! This is the handler for an exception from INPUT. 
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IF ERR = 11 
THEN 

SELECT ERL 
CASE 10 

RESUME 20 
CASE 20 

RESUME 30 
CASE ELSE 

ON ERROR GO BACK 
END SELECT 

ELSE 

ON ERROR GO BACK 
END IF 


1 End of file 

1 No more input, begin searching tree 

! No more items to search for, traverse 
! tree 

! Resignal the error 
! Resignal the error 


End_of_program: 

I + 

! This is the end of the program. 

i _ 

END 

%TITLE 'LIB$ Tree Example in BASIC V2' 

%SBTTL 'Function to print a node during tree traversal' 

100 FUNCTION LONG Print_node (Node_type Node, LONG Dummy) 

! + 

! Print the string contained in the current node. 

OPTION TYPE = EXPLICIT 

RECORD Node_type 

BYTE Header (9) 

LONG Seq_Num 

LONG Length 

STRING Text =80 

END RECORD Node_type 

PRINT Node::Seq_Num, SEG$ (Node::Text, 1%, Node::length) 

Print_node =1% 

END FUNCTION 

%TITLE 'LIB$ Tree Example in BASIC V2' 

%SBTTL 'Function to allocate VM for a node' 

200 FUNCTION LONG Alloc_node ( 

Tree_element 
LONG 
LONG 

! + 

! Allocate virtual memory for a new node. Rec is the 
! data record to be entered into the newly 
I allocated node. RET_ADDR will contain the address 
! of the allocated memory. 


& 

Rec, & 
Ret_addr, & 
Dummy) 


! Header 

! Sequence number 
! Length 
! String 


OPTION TYPE = EXPLICIT 

RECORD Tree_element 

LONG Seq_num 

LONG Text_len 

STRING Text = 80 

END RECORD Tree_element 

DECLARE LONG Status_code, Data_len 

EXTERNAL LONG FUNCTION LIB$GET_VM 


! Define the structure of our 
! record. This record could 
! contain many useful data items 
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EXTERNAL SUB LIB$M0VC3 


! + 

! Calculate the length of our data. 

i _ 

Data_len = 8% + Rec::Text_len 

! + 

i Allocate node: 10 for header, plus the length of our data. 


Status_code = LIB$GET_VM (10% + Data_len, Ret_addr) 

CALL LIB$STOP (Status_code) IF (Status_code AND 1%) <> 1% 

! + 

! Store the data in the newly allocated virtual memory. Note 
! that we pass the first field by reference, which is the same 
! as passing the address of the entire record. We add 10 to the 
! address of the VM and pass the result by value so LIB$MOVC3 
! receives the address that marks the beginning of our data in 
1 the node. 

i _ 


CALL LIB$MOVC3 (Data_Len, Rec::Seq_Num, (Ret_addr + 10%) BY VALUE) 
Alloc_node =1% 

END FUNCTION 


%TITLE 'LIB$ Tree Example in BASIC V2' 
%SBTTL 'Function to compare two nodes' 
300 FUNCTION LONG Compare_node_3 ( 

Tree_element 

Node_type 

LONG 


Rec, 

Node, 

Dummy) 


& 

& 

& 


OPTION TYPE = EXPLICIT 


RECORD Tree_element 
LONG Seq_num 
LONG Text_len 
STRING Text =80 
END RECORD Tree_element 

RECORD Node_type 

BYTE Header (9) 

LONG Seq_Num 
LONG Length 
STRING Text =80 
END RECORD Node_type 

EXTERNAL LONG FUNCTION Compare_node 


! Define the structure of our 
! record. This record could 
! contain many useful data items 


1 Header 

! Sequence number 
! Length 
! String 

2 


I + 

i Call the 2 argument version of the compare routine. 

i _ 

Compare_node_3 = Compare_node_2 ( Rec, Node ) 

END FUNCTION 

310 FUNCTION LONG Compare_node_2 ( & 

Tree_element Rec, & 

Node_type Node) 


This function compares the string described by Key_string with 
the string contained in the data node Node, and returns 0 
if the strings are equal, -1 if Key_string is < Node, and 
1 if Key_string > Node. 
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OPTION TYPE = EXPLICIT 

RECORD Tree_element 

LONG Seq_num 

LONG Text_len 

STRING Text =80 

END RECORD Tree_element 

RECORD Node_type 

BYTE Header (9) 

LONG Seq_Num 

LONG Length 

STRING Text =80 

END RECORD Node_type 

DECLARE STRING Node_string, Key_string 

! + 

! Return the result of the comparison. 

i _ 

Node_string = SEG$ (Node::Text, 1, Node::Length) 
Key_string = SEG$ (Rec::Text, 1, Rec::Text_len) 

SELECT Key_string 
CASE < Node_string 

Compare_node_2 = -1% 

CASE > Node_string 

Compare_node_2 =1% 

CASE ELSE 

Compare_node_2 =0% 

END SELECT 

END FUNCTION 

%TITLE 'LIB$ Tree Example in BASIC V2' 

%SBTTL 'Function to display node data' 

400 SUB Display_node ( & 

Node_type Node ) 

! + 

! This routines prints the data into the node of the tree 

! once LIB$LOOKUP_TREE has been called to find the node 


! Define the structure of our 
! record. This record could 
! contain many useful data items 


! Header 

l Sequence number 
! Length 
! String 


RECORD Node type 


BYTE 

Header (9) 

! Header 

LONG 

Seq Num 

! Sequence number 

LONG 

Length 

! Length 

STRING 

Text = 80 

! String 

END RECORD 

Node type 



DECLARE STRING Node_string 

Node_string = SEG$ (Node::Text, 1, Node::Length) 

PRINT "The sequence number for ";'"';Node_string;'"';" is ";Node::Seq_num 
END SUB 


LIB-253 





LIB$INSERT_TREE 


The following BASIC example shows the use of LIB$INSERT_TREE, 
LIB$LOOKUP_TREE, and LIB$TRAVERSE_TREE. 

The output generated by this program is as follows: 

$ run tree 

Enter one word per line, A Z to begin searching the tree 

> apple 

> orange 

> peach 

> pear 

> grapefruit 

> lemon 

> |Ctrl/z| 

You will now be prompted for words to find. Enter one per line. 
Word to find? lime 

The word you entered does not appear in the tree 

Word to find? orange 

The sequence number for "orange" is 2 

Word to find? (ctri/zj 

The following is a dump of the tree. Notice that the words 
are in alphabetical order 

1 apple 

5 grapefruit 

6 lemon 

2 orange 

3 peach 

4 pear 

$ 
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LIBSINSQHI—Insert Entry at Head of Queue 

The Insert Entry at Head of Queue routine inserts a queue entry at the head 
of the specified self-relative interlocked queue. LIB$INSQHI makes the VAX 
INSQHI 1 instruction available as a callable routine. 

Format 

LIBSINSQHI entry .header [,retry-count] 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Arguments 

entry 

OpenVMS usage unspecified 
type unspecified 

access modify 

mechanism by reference, array reference 

Entry to be inserted by LIB$INSQHI. The entry argument contains the address 
of this signed quadword-aligned array that must be at least eight bytes long. 
Bytes following the first eight bytes can be used for any purpose by the calling 
program. 

header 

OpenVMS usage quadword_signed 
type quadword integer (signed) 

access modify 

mechanism by reference 

Queue header specifying the queue into which entry is to be inserted. The 
header argument contains the address of this signed aligned quadword integer. 
Header must be initialized to zero before first use of the queue; zero means an 
empty queue. 

retry-count 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

The number of times the insertion is to be retried in case of secondary-interlock 
failure of the queue instruction in a processor-shared memory application. The 
retry-count argument is the address of an unsigned longword that contains the 
retry count value. A value of 1 causes no retries. The default value is 10. 


1 On AXP systems, OpenVMS AXP instructions perform the equivalent operation. 


cond_value 
longword (unsigned) 
write only 
by value 
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Description 

The queue into which LIB$INSQHI inserts an entry can be in process-private, 
processor-private, or processor-shareable memory to implement per-process, 
per-processor, or across-processor queues. 

A queue is a doubly linked list. A Run-Time Library routine specifies a queue 
entry by its address. Two longwords, a forward link and a backward link, define 
the location of the entry in relation to the preceding and succeeding entries. 

A self-relative queue is a queue in which the links between entries are 
displacements; the two longwords represent the displacements of the current 
entry's predecessor and successor. The VAX instructions INSQHI, INSQTI, 
REMQHI, and REMQTI allow you to insert and remove an entry at the head 
or tail of a self-relative queue. Each queue instruction has a corresponding 
Run-Time Library routine. 

The self-relative queue instructions are interlocked and cannot be interrupted, 
so that other processes cannot insert or remove queue entries while the current 
program is doing so. Since the operation requires changing two pointers at the 
same time, a high-level language cannot perform this operation without calling 
the Run-Time Library queue access routines. 

When you use these routines, cooperating processes can communicate without 
further synchronization and without danger of being interrupted, either on a 
single processor or in a multiprocessor environment. The queue Access routines 
are also useful in an AST environment; they allow you to add or remove an entry 
from a queue without being interrupted by an asynchronous system trap. 

Condition Values Returned 


SS$_N ORMAL 

LIB$_ONEENTQUE 

LIB$_SECINTFAI 


SS$_ROPRAND 


Routine successfully completed. The entry was 
added to the front of the queue, and the resulting 
queue contains more than one entry. 

Routine successfully completed. The entry was 
added to the front of the queue, and the resulting 
queue contains one entry. 

A secondary interlock failure occurred; the 
insertion was attempted the number of times 
specified by retry-count. This is a severe error. 
The queue is not modified. This condition can 
occur only when the queue is in memory being 
shared between two or more processors. 

Reserved operand fault. Either the entry or the 
header is at an address that is not quadword 
aligned, or the header address equals the entry 
address. 
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Examples 


1. INTEGER*4 FUNCTION INSERT_Q (QENTRY) 

COMMON/QUEUES/QHEADER 

INTEGER* 4 QENTRY(10), QHEADER(2) 

INSERT_Q = LIB$INSQHI (QENTRY, QHEADER) 

RETURN 

END 

This is a FORTRAN application using processor-shared memory. 

2. COM (QUEUES) QENTRY%(9), QHEADER%(1) 

EXTERNAL INTEGER FUNCTION LIB$INSQHI 

IF LIB$INSQHI (QENTRY%() BY REF, QHEADER%() BY REF) AND 1% 
THEN GOTO 1000 


1000 REM INSERTED OK 

In BASIC and FORTRAN, queues can be quadword aligned in a named 
COMMON block by using a linker option file to specify PSECT alignment. 
The Run-Time Library routine LIB$GET_VM returns memory that is 
quadword aligned. Therefore, you should use LIB$GET_VM to allocate 
the virtual memory for a queue. For instance, to create a COMMON block 
called QUEUES, use the LINK command with the FILE/OPTIONS qualifier, 
where FILE.OPT is a linker option file containing the line: 

PSECT = QUEUES, QUAD 
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LIBSINSQTI—Insert Entry at Tail of Queue 

The Insert Entry at Tail of Queue routine inserts a queue entry at the tail of the 
specified self-relative interlocked queue. LIB$INSQTI makes the VAX INSQTI 1 
instruction available as a callable routine. 

Format 

LIBSINSQTI entry header [,retry-count] 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Arguments 

entry 

OpenVMS usage unspecified 
type unspecified 

access modify 

mechanism by reference, array reference 

Entry to be inserted at the tail of the queue by LIB$INSQTI. The entry argument 
contains the address of this signed quadword-aligned array that must be at least 
eight bytes long. Bytes following the first eight bytes can be used for any purpose 
by the calling program. 

header 

OpenVMS usage quadword_signed 
type quadword integer (signed) 

access modify 

mechanism by reference 

Queue header specifying the queue into which the queue entry is to be inserted. 
The header argument contains the address of this signed aligned quadword 
integer. Header must be initialized to zero before first use of the queue; zero 
means an empty queue. 

retry-count 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

The number of times the insertion is to be retried in case of secondary-interlock 
failure of the queue instruction in a processor-shared memory application. The 
retry-count argument is the address of a longword which contains the retry 
count value. The default value is 10. 


1 On AXP systems, OpenVMS AXP instructions perform the equivalent operation. 


cond_value 
longword (unsigned) 
write only 
by value 
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Description 

The queue into which LIB$INSQTI inserts an entry can be in process-private, 
processor-private, or processor-shareable memory to implement per-process, 
per-processor, or across-processor queues. 

A queue is a doubly linked list. A Run-Time Library routine specifies a queue 
entry by its address. Two longwords, a forward link and a backward link, define 
the location of the entry in relation to the preceding and succeeding entries. 

A self-relative queue is a queue in which the links between entries are 
displacements; the two longwords represent the displacements of the current 
entry’s predecessor and successor. The VAX instructions INSQHI, INSQTI, 
REMQHI, and REMQTI 1 allow you to insert and remove an entry at the head 
or tail of a self-relative queue. Each queue instruction has a corresponding 
Run-Time Library routine. 

The self-relative queue instructions are interlocked and cannot be interrupted, 
so that other processes cannot insert or remove queue entries while the current 
program is doing so. Since the operation requires changing two pointers at the 
same time, a high-level language cannot perform this operation without calling 
the Run-Time Library queue access routines. 

When you use these routines, cooperating processes can communicate without 
further synchronization and without danger of being interrupted, either on a 
single processor or in a multiprocessor environment. The queue Access routines 
are also useful in an AST environment; they allow you to add or remove an entry 
from a queue without being interrupted by an asynchronous system trap. 


Condition Values Returned 

SS$_N ORMAL 

LIB$_ONEENTQUE 

LIB$_SECINTFAI 


SS$_ROPRAND 


Routine successfully completed. The entry was 
added to the tail of the queue: the resulting 
queue contains more than one entry. 

Routine successfully completed. The entry was 
added to the tail of the queue: the resulting 
queue contains one entry. 

A secondary interlock failure occurred; the 
insertion was attempted the number of times 
specified by retry-count. This is a severe error. 
The queue is not modified. This condition can 
occur only when the queue is in memory being 
shared between two or more processors. 
Reserved operand fault. Either the entry or the 
header is at an address that is not quadword 
aligned, or the header address equals the entry 
address. 


1 On AXP systems, OpenVMS AXP instructions perform the equivalent operations. 
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LIB$INSV—Insert a Variable Bit Field 

The Insert a Variable Bit Field routine replaces the variable bit field specified by 
the base, position, and size arguments with bits 0 through (size - 1) of the source 
field. If the size of the bit field is zero, nothing is inserted. LIB$INSV makes the 
VAX INSV 1 instruction available as a callable routine. 


Format 


LIB$INSV longword-integer-source .position .size ,base-address 


Returns 


None. 


Arguments 

longword-integer-source 

OpenVMS usage longword_signed 
type longword integer (signed) 

access read only 

mechanism by reference 

Source field to be inserted by LIB$INSV. The longword-integer-source 
argument is the address of a signed longword integer that contains this source 
field. 

position 

OpenVMS usage longword_signed 
type longword integer (signed) 

access read only 

mechanism by reference 

Bit position relative to the base address where insertion of longword-integer- 
source is to begin. The position argument is the address of a longword integer 
that contains this relative bit position. 

size 

OpenVMS usage byte_unsigned 
type byte (unsigned) 

access read only 

mechanism by reference 

Size of the bit field to be inserted by LIB$INSV. The size argument is the address 
of an unsigned byte which contains the size of this bit field. The maximum size is 
32 bits. 

base-address 

OpenVMS usage address 
type address 

access read only 

mechanism by value 

Field into which LIB$INSV writes the source field. The base-address argument 
is an unsigned longword containing the base address of this aligned bit string. 

1 On AXP systems, OpenVMS AXP instructions perform the equivalent operation. 
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Condition Value Signaled 

SS$_ROPRAND A reserved operand fault is signaled if a size 

greater than 32 is specified. 

Examples 

1. INTEGER*4 COND_VALUE 

CALL LIB$INSV (4, 0, 3, COND_VALUE) 

This example shows how to set bits 0 through 2 of longword COND_VALUE 
to the value 4 in FORTRAN. 

2. DECLARE INTEGER COND_VALUE 

CALL LIB$INSV (4%, 0%, 3%, COND_VALUE) 

This example uses BASIC to set bits 0 through 2 of longword COND_VALUE 
to the value 4. 
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LIB$INT_OVER—Integer Overflow Detection 


AXP 


Format 


The Integer Overflow Detection routine enables or disables integer overflow 
detection for the calling routine activation. The previous integer overflow enable 
setting is returned. 

This routine is available on OpenVMS AXP systems in translated form and is 
applicable to translated VAX images only. ♦ 


LIB$INT_OVER new-setting 


Returns 


OpenVMS usage longword_unsigned 
type longword (unsigned) 

access write only 

mechanism by value 

Old integer overflow enable setting (the previous contents of SF$W_PSW[PSW$V_ 
IV] in the caller’s frame). 


Argument 

new-setting 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

New integer overflow enable setting. The new-setting argument is the address 
of an unsigned longword which contains the new integer overflow enable setting. 
Bit 0 set to 1 means enable, bit 0 set to 0 means disable. 


Description 

The caller’s stack frame will be modified by this routine. 

LIB$INT_OVER affects only the current routine activation and does not affect 
any of its callers or any routines that it may call. However, the setting remains 
in effect for any routines which are subsequently entered through a JSB entry 
point. 

Condition Values Returned 

None. 
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Example 


INTOVF: 

ROUTINE OPTIONS (MAIN); 





DECLARE 

LIB$INT_OVER ENTRY (FIXED BINARY 

(7)) 

/* 

Address of byte for 




/* 

enable/disable 





/* 

setting 

*/ 


RETURNS (FIXED BINARY (31)); 


/* 

Old setting 

*/ 

DECLARE 

DISABLE FIXED BINARY (7) INITIAL 

(0) 

STATIC READONLY; 


DECLARE 

(A,B) FIXED BINARY (7); 






ON FIXEDOVERFLOW PUT SKIP LIST ('Overflow'); 

A = 127; 

B = A + 2; 

PUT LIST ('In MAIN'); 

BEGIN; 

DECLARE RESULT FIXED BINARY (31); 

/* Disable recognition of integer overflow in this block */ 

RESULT = LIB$INT_OVER (DISABLE); 

B = A + 2; 

PUT SKIP LIST ('In BEGIN block'); 

CALL Q; 

Q: routine; 

B = A + 2; 

PUT LIST ('In Q'); 

END Q; 

END /* Begin */; 

END INTOVF; 

This PL/I routine shows how to use LIB$INT_OVER to enable or disable the 
detection of integer overflow. Note that in PL/I integer overflow is always enabled 
unless explicitly overridden by a call to this routine. However, disabling integer 
overflow is only effective for the block which calls this routine; descendent blocks 
are unaffected. The output generated by this PL/I program is as follows: 

In MAIN 

In BEGIN block 
Overflow In Q 
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LIBSLEN—Length of String Returned as Longword Value 

The Length of String Returned as Longword Value routine returns the length of a 
string. 


Format 

UB$LEN source-string 

Returns 

OpenVMS usage word_unsigned 
type word (unsigned) 

access write only 

mechanism by value 

Length of the source string, extracted and zero-extended to 32 bits. 

Argument 

source-string 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Source string whose length is returned by LIB$LEN. The source-string 
argument contains the address of a descriptor pointing to this source string. 


Description 

The maximum length of an OpenVMS string is 65,535 characters. 

The BASIC and FORTRAN intrinsic function LEN generates equivalent in-line 
code at run time. Therefore, it is more efficient for BASIC and FORTRAN users 
to use the intrinsic function LEN than to call LIB$LEN. 

If you need both the length of the string and the address of its first byte, you 
should use LIB$ANALYZE_SDESC instead. 

Condition Values Returned 

None. 
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LIB$LOCC—Locate a Character 

The Locate a Character routine locates a character in a string by comparing 
successive bytes in the string with the character specified. The search continues 
until the character is found or the string has no more characters. LIB$LOCC 
makes the VAX LOCC 1 instruction available as a callable routine. 


Format 

UB$LOCC character-string ,source-string 

Returns 


OpenVMS usage longword_unsigned 
type longword (unsigned) 

access write only 

mechanism by value 

The relative position from the start of source-string to the first equal character 
or zero if no match is found. 


Arguments 

character-string 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

String whose initial character is used by LIB$LOCC in the search. The 
character-string argument contains the address of a descriptor pointing to 
this string. Only the first character of character-string is used, and its length 
is not checked. 

source-string 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

String to be searched by LIB$LOCC. The source-string argument is the address 
of a descriptor pointing to this character string. 


Description 

LIB$LOCC returns the position of the first equal character relative to the start 
of the source string as an index. An index is the relative position of the first 
occurrence of a substring in the source string. If no character matches, or if the 
string has a length of zero, then a zero is returned, indicating that the character 
was not found. 


1 On AXP systems, OpenVMS AXP instructions perform the equivalent operation. 
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Condition Values Returned 

None. 

Examples 


1. IDENTIFICATION DIVISION. 
PROGRAM-ID. LIBLOC. 

ENVIRONMENT DIVISION. 

DATA DIVISION. 

WORKING-STORAGE SECTION. 


01 

SEARCH-STRING 

PIC X(2 6) 

VALUE "ABCDEFGHIJKLMNOPQRSTUVWXYZ" 

01 

SEARCH-CHAR 

PIC X. 

01 

IND-POS 

PIC 9(9) USAGE IS COMP. 

01 

DISP-IND 

PIC 9(9). 


ROUTINE DIVISION. 


001-MAIN. 

MOVE SPACE TO SEARCH-CHAR. 

DISPLAY " ". 

DISPLAY "ENTER SEARCH CHARACTER: " WITH NO ADVANCING. 

ACCEPT SEARCH-CHAR. 

CALL "LIB$LOCC" 

USING BY DESCRIPTOR SEARCH-CHAR, SEARCH-STRING 
GIVING IND-POS. 

IF IND-POS = ZERO 
DISPLAY 

"CHAR ENTERED (" SEARCH-CHAR ") NOT A VALID SEARCH CHAR" 
STOP RUN. 

MOVE IND-POS TO DISP-IND. 

DISPLAY 

"SEARCH CHAR (" SEARCH-CHAR ") WAS FOUND IN POSITION " 
DISP-IND. 

GO TO 001-MAIN. 


This COBOL program accepts a character as input and returns as output the 
character’s position in a search string. The output generated by this COBOL 
program is as follows: 

$ RUN LIBLOC 

ENTER SEARCH CHARACTER: X 

SEARCH CHAR (X) WAS FOUND IN POSITION 000000024 
ENTER SEARCH CHARACTER: Y 

SEARCH CHAR (Y) WAS FOUND IN POSITION 000000025 
ENTER SEARCH CHARACTER: B 

SEARCH CHAR (B) WAS FOUND IN POSITION 000000002 

ENTER SEARCH CHARACTER: b 
CHAR ENTERED (b) NOT A VALID SEARCH CHAR 
$ 

Notice that uppercase and lowercase letters are not considered equal. 
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2 . 10 ! + 

! This is an BASIC program demonstrating the 
! use of LIB$LOCC. 

I _ 

EXTERNAL INTEGER FUNCTION LIB$LOCC 
1 % = 0 

CHARSTR$ = 'DAY' 

SRCSTR$ = 'ONE DAY AT A TIME' 

1% = LIB$LOCC(CHARSTR$, SRCSTR$) 

PRINT 1% 

90 END 

This BASIC example also shows the use of LIB$LOCC. The output generated 
by this BASIC program is “5”. 


LIB-267 




LIB$LOOKUP_KEY 


LIB$LOOKUP_KEY—Look Up Keyword in Table 

The Look Up Keyword In Table routine scans a table of keywords to find one that 
matches the keyword or keyword abbreviation specified by search-string. 

Format 

LIB$LOOKUP_KEY search-string ,key-table-array [,key-value] [.keyword-string] [.resultant-length] 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Arguments 

search-string 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

String for which LIB$LOOKUP_KEY will search in the keyword table. The 
search-string argument is the address of a descriptor pointing to this string. 

key-table-array 

OpenVMS usage unspecified 

type unspecified 

access read only 

mechanism by reference, array reference 

Keyword table. The key-table-array argument contains the address of an array 
that is this keyword table. 

key-value 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access write only 

mechanism by reference 

Associated value ofthe keyword found by LIB$LOOKUP_KEY. The key- 
value argument contains the address of an unsigned longword into which 
LIB$LOOKUP_KEY writes the associated value of the matched keyword. 

keyword-string 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor 

Full keyword string matched. The keyword-string argument contains the 
address of a character string descriptor. LIB$LOOKUP_KEY writes the complete 
text of the matched keyword into the character string. 
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resultant-length 

OpenVMS usage word_unsigned 
type word (unsigned) 

access write only 

mechanism by reference 

Number of characters in the keyword, independent of padding. The resultant- 
length argument is the address of an unsigned word integer that contains the 
number of characters in the keyword. LIB$LOOKUP_KEY writes the length of 
the keyword into resultant-length. 


Description 

LIB$LOOKUP_KEY is intended to help programmers to write utilities that have 
command qualifiers with values. 

LIB$LOOKUP_KEY locates a matching keyword or keyword abbreviation by 
comparing the first n characters of each keyword in the keyword table with the 
supplied string, where n is the length of the supplied string. 

When a keyword match is found, the following information is optionally returned 
to the caller. 

• The longword value associated with the matched keyword 

• The full keyword string (any descriptor type) 

An exact match is found if the length of the keyword found is equal to the length 
of the supplied string. 

If an exact keyword match is found, no further processing is performed, and a 
normal return status is returned to the caller. Otherwise, after a match has been 
found, the rest of the keyword table is scanned. If an additional match is found, 
a "not enough characters" return status is returned to the caller. If the keyword 
table contains a keyword that is an abbreviation of another keyword in the table, 
an exact match can occur for short abbreviations. 

See Figure LIB-7 for the structure of the keyword table, which the calling 
program creates for this routine. 

Figure LIB-7 Keyword Table 


Vector 


Vector-Count 


Address of Keyword String 

\ 

f Keyword String 

Associated Keyword Value 

• 

• 

• 

Counted-ASCII String 


ZK-1976-GE 

Vector-count is the number of longwords that follow, and counted-ASCII- 
string starts with a byte that is the unsigned count of the number of ASCII 
characters that follow. 
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Because of the format of the keyword table, this routine cannot be called easily 
from high-level languages. The examples show how to use a macro, $LIB_KEY_ 
TABLE, to construct a keyword table from MACRO or BLISS. A separate example 
shows how a table could be constructed in FORTRAN. 

Use of the $LIB_KEY_TABLE macro results in data that is not position- 
independent code (PIC). If your application requires PIC data, you must fill 
in the address of the keyword strings at execution time. See the FORTRAN 
example for a demonstration of this technique. 


Condition Values Returned 


SS$_N ORMAL 
LIB$_AMBKEY 

LIB$_INVARG 
LIB$_IN SVIRMEM 

LIB$_STRTRU 

LIB$_UNRKEY 


Routine successfully completed. A unique 
keyword match was found. 

Multiple keyword match found. Not enough 
characters were specified to allow a unique 
match. 

Invalid arguments, not enough arguments, and 
/or bad keyword table. 

Insufficient virtual memory to return keyword 
string. This is only possible if keyword-string 
is a dynamic string. 

String truncated. 

The keyword you specified does not appear in the 
keyword table you specified. 


Examples 

1. KEYTABLE: 

$LIB_KEY_TABLE < - 

<ADD, 1>, - 
<DELETE, 2>, - 
<EXIT, 3» 

This VAX MACRO fragment defines a keyword table named KEYTABLE 
containing the three keywords ADD, DELETE, and EXIT with associated 
keyword values of 1, 2, and 3, respectively. 

The $LIB_KEY_TABLE macro is supplied in the default macro library 
SYS$LIBRARY:STARLET.MLB. Because this library is automatically 
searched by the assembler, you do not have to specify it in the DCL command 
MACRO. 


2. LIBRARY 'SYS$LIBRARY:STARLET.L32'; 

OWN 

KEYTABLE: $LIB_KEY_TABLE ( 

(ADD, 1), 

(DELETE, 2), 

(EXIT, 3)); 

This BLISS code fragment specifies that SYS$LIBRARY:STARLET.L32 is 
to be searched to resolve references. It defines a keyword table named 
KEYTABLE containing the three keywords ADD, DELETE, and EXIT with 
associated keyword values of 1, 2, and 3, respectively. 
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The $LIB_KEY_TABLE macro is supplied in the BLISS library 
SYS$LIBRARY:STARLET.L32 and in the BLISS require file 
SYS$LIBRARY:STARLET.REQ. BLISS does not automatically search either of 
these files so you must explicitly cause them to be searched by including the 
appropriate LIBRARY or REQUIRE statement in your module. You should 
use the precompiled library because it is more efficient for the compiler. 


3. PARAMETER ( 

1 MAXKEYSIZE = 6, ! Maximum keyword size 

2 NKEYS =3) ! Number of keywords 

BYTE KEYWORDS (MAXKEYSIZE+1, NKEYS) 

INTEGER*4 KEYTABLE (0:NKEYS*2) 

DATA KEYWORDS / 

1 3,'A','D','D',' ! Counted ASCII 'ADD' 

2 6,'D','E', 'L' ,'E','T','E', ! Counted ASCII 'DELETE' 

3 4,'E','X','I','T',' ',' '/ ! Counted ASCII 'EXIT' 


KEYTABLE(0) = NKEYS*2 

KEYTABLE(1) = %LOC(KEYWORDS(1,1)) 

KEYTABLE(2) = 1 

KEYTABLE(3) = %LOC(KEYWORDS(1,2)) 
KEYTABLE(4) = 2 

KEYTABLE(5) = %LOC(KEYWORDS(1,3)) 
KEYTABLE(6) = 3 


! Number of longwords to follow 
! Address of keyword string 
! Keyword value for 'ADD' 

! Address of keyword string 
! Keyword value for 'DELETE' 

! Address of keyword string 
! Keyword value for 'EXIT' 


This FORTRAN code fragment constructs a keyword table named KEYTABLE 
containing the three keywords ADD, DELETE, and EXIT with associated 
keyword values of 1, 2, and 3, respectively. This construction method results 
in position-independent coded data, although the generated code for the 
typical FORTRAN module contains other non-PIC values. 
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LIB$LOOKUP_TREE—Look Up an Entry in a Balanced Binary Tree 

The Look Up an Entry in a Balanced Binary Tree routine looks up an entry in a 
balanced binary tree. 


Format 


LIB$LOOKUP_TREE treehead ,symbol ,user-compare-routine ,new-node 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Arguments 


treehead 

OpenVMS usage 

type 

access 

mechanism 


address 
address 
read only 
by reference 


Tree head for the binary tree. The treehead argument is the address of an 
unsigned longword that is this tree head. 


symbol 

OpenVMS usage user_arg 
type longword (unsigned) 

access unspecified 

mechanism unspecified 

Key to be looked up in the binary tree. 

user-compare-routine 

OpenVMS usage procedure 
type procedure value 

access function call (before return) 

mechanism by value 

User-supplied compare routine that LIB$LOOKUP_TREE calls to compare a 
symbol with a node. The value returned by the compare routine indicates the 
relationship between the symbol key and the current node. 

The following list gives possible values of the user-compare-routine argument 
and their meanings. 


Value 

Description 

Negative 

Zero 

Positive 

symbol is less than the current node 
symbol is equal to the current node 
symbol is greater than the current node 


For more information on the compare routine, see “Call Format for a Compare 
Routine” in the Description section. 
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new-node 

OpenVMS usage address 
type longword (unsigned) 

access write only 

mechanism by reference 

Location where the new symbol was found. The new-node argument is the 
address of an unsigned longword that is the new node location. 


Description 


Call Format for a Compare Routine 

The call format of a compare routine is as follows: 

user-compare-routine symbol,comparison-node [,user-data] 

LIB$LOOKUP_TREE passes both the symbol and comparison-node arguments 
to the compare routine, using the same passing mechanism that was used to pass 
them to LIB$LOOKUP_TREE. The user-data argument is passed in the same 
way, but its use is optional. 

The user-compare-routine argument in the call to LIB$LOOKUP_TREE 
specifies the compare routine. This argument is required. LIB$LOOKUP_TREE 
calls the compare routine for every node except the first node in the tree. 

The value returned by the compare routine is the result of comparing the symbol 
key with the current node. Listed below are the possible values returned by the 
compare routine. 


Value 

Description 

Negative 

Zero 

Positive 

symbol is less than the current node 
symbol is equal to the current node 
symbol is greater than the current node 


For an example of a user-supplied compare routine written in BASIC, see the 
description of LIB$INSERT_TREE. 


Condition Values Returned 

LIB$_NORMAL Success. The key was found. 

LIB$_KEYNOTFOU Error. The key was not found. 


Example 


The BASIC example provided in the description of LIB$INSERT_TREE also 
demonstrates how to use LIB$LOOKUP_TREE. Please refer to that example for 
assistance in using this routine. 
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LIB$LP_LINES—Lines on Each Printer Page 

The Lines on Each Printer Page routine computes the default number of lines on 
a printer page. This routine can be used by native-mode OpenVMS utilities that 
produce listing files and paginate files. 


Format 

UB$LP_LINES 

Returns 


OpenVMS usage longword_signed 
type longword integer (signed) 

access write only 

mechanism by value 

The default number of lines on a physical printer page. If the logical name 
translation or conversion to binary fails, a default value of 66 is returned. 


Arguments 

None. 


Description 

LIB$LP_LINES computes the default number of lines on a printer page. This 
routine can be used by native-mode OpenVMS utilities that produce listing files 
and paginate files. The algorithm used by LIB$LP_LINES is: 

1. Translate the logical name SYS$LP_LINES. 

2. Convert the ASCII value obtained to a binary integer. 

3. Verify that the resulting value is in the range [30:255]. 

4. If any of the prior steps fail, return the default paper size of 66 lines. 

You can use LIB$LP_LINES to monitor the current default length of the line 
printer page. You can also supply your own default length for the current process. 
United States standard paper stock permits 66 lines on each physical page. 

If you are writing programs for a utility that formats a listing file to be printed 
on a line printer, you can use LIB$LP_LINES to make your utility independent 
of the default page length. Your program can use LIB$LP_LINES to obtain the 
current length of the page. It can then calculate the number of lines of text on 
each page by subtracting the lines used for margins and headings. 

The following is one suggested format. 

1. Three lines for the top margin 

2. Three lines for the bottom margin 

3. Three lines for listing heading information, consisting of: 

a. A language-processor identification line 

b. A source-program identification line 

c. One blank line 
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Condition Values Returned 

None. 

Examples 

1. lplines = LIB$LP_LINES() 

PRINT 10, lplines 

10 Format (' Line printer page = ',15,' lines.') 

end 

This FORTRAN program displays the current default length of the line 
printer page. 

2. 100 EXTERNAL INTEGER FUNCTION LIB$LP_LINES 
200 DECLARE INTEGER LPLINES 

300 LPLINES = LIB$LP_LINES 

400 PRINT "Line printer page = "; LPLINES 

32767 END 

This BASIC program displays the current default length of the line printer 
page. 

3. PROGRAM LINES(OUTPUT); 

FUNCTION LIB$LP_LINES : INTEGER; 

EXTERN; 

BEGIN 

WRITELN('Line printer page = ',LIB$LP_LINES,' lines.'); 

END. 

This Pascal program displays the current default length of the line printer 
page. 
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LIB$MATCHC—Match Characters, Return Relative Position 

The Match Characters and Return Relative Position routine searches a source 
string for a specified substring and returns an index, which is the relative position 
of the first occurrence of a substring in the source string. The relative character 
positions returned by LIB$MATCHC are numbered 1, 2, . . . , n. Thus, zero 
means that the substring was not found. 


Format 

LIB$MATCHC sub-string ,source-string 


Returns 


OpenVMS usage longword_unsigned 
type longword (unsigned) 

access write only 

mechanism by value 

The relative position of the first character of the substring if found, or zero if not 
found. 


Arguments 

sub-string 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Substring to be found. The sub-string argument is the address of a descriptor 
pointing to this substring. 

source-string 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Source string to be searched by LIB$MATCHC. The source-string argument is 
the address of a descriptor pointing to this source string. 


Description 

LIB$MATCHC searches a source string for a specified substring and returns an 
index, which is the relative position of the first occurrence of a substring in the 
source string. 

The relative character positions returned by LIB$MATCHC are numbered 1, 

2, ... , n. Thus, zero means that the substring was not found. 
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If the substring has a zero length, LIB$MATCHC returns the value 1, indicating 
success, no matter how long the source string is. If the source string has a zero 
length and the substring has a nonzero length, zero is returned, indicating that 
the substring was not found. 

Condition Values Returned 

None. 
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LIB$MATCH_COND—Match Condition Values 

The Match Condition Values routine checks to see if a given condition value 
matches a list of condition values that you supply. 


Format 

LIB$MATCH_COND match-condition-value ,compare-condition-value 

Returns 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access write only 

mechanism by value 

A zero, if the input condition value did not match any condition value in the list, 
on - 1, for a match between the first argument and the ith argument. 

Arguments 

match-condition-value 

OpenVMS usage cond_value 
type longword (unsigned) 

access read only 

mechanism by reference 

Condition value to be matched. The match-condition-value argument is the 
address of an unsigned longword that contains this condition value. 

compare-condition-value 

OpenVMS usage cond_value 
type longword (unsigned) 

access read only 

mechanism by reference 

The condition values to be compared to match-condition-value. The compare- 
condition-value arguments are the addresses of the unsigned longwords that 
contain these condition values. 


Description 

LIB$MATCH_COND checks for a match between the condition value addressed 
by match-condition-value and the condition values addressed by the 
subsequent arguments. Each argument is the address of a longword containing a 
condition value. 

LIB$MATCH_COND is provided for programmers who want to match a list of 
one or more condition values. It is designed to be used in multi-path branch 
statements available in most higher-level languages. 

LIB$MATCH_COND compares the portion (STS$V_COND_ID) of the condition 
value referenced by the first argument to the same portion of the condition value 
referenced by the second through Nth arguments. If the facility-specific bit 
(STS$V_FAC_SP = bit 15) is clear in match-condition-value (meaning that the 
condition value is systemwide rather than facility specific), the facility code field 
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(STS$V_FAC_NO = bits 27:17) is ignored and only the STS$V_MSG_ID fields 
(bits 15:3) are compared. 

The routine returns a zero if a match is not found, a 1 if the condition 
value matches the first condition value in the list (the second argument), a 
2 if it matches the second condition value (the third argument), and so on. 
LIB$MATCH_COND checks for null argument entries in the argument list. 

When LIB$MATCH_COND is called with only two arguments, the possible values 
for the value returned are true (1) or false (zero). 

Each condition handler must examine the signal argument vector to determine 
which condition is being signaled. If the condition is not one that the handler 
knows about, the handler should resignal. A handler should not assume that 
only one kind of condition can occur in the routine which established it or in 
any routines it calls. However, because a condition value may be modified by an 
intervening handler, each handler should only compare that part of the condition 
value that distinguishes it from another. 

Condition Values Returned 

None. 


Example 


c+ 

C This FORTRAN program demonstrates the use of 
C LIB$MATCH_COND. 

C 

C Declare handler routine as external. 

C- 

EXTERNAL HANDLER 
C+ 

C Declare the handler that will be used. 

C- 

TYPE *, 'Establishing handler...' 

CALL LIB$ESTABLISH ( HANDLER ) 

OPEN ( UNIT = 1, NAME = 'MATCH.DAT', STATUS = 'OLD') 

C+ 

C Revert to normal error processing. 

C- 

CALL LIB$REVERT 
CLOSE ( UNIT = 1 ) 

CALL EXIT 
END 
C+ 

C This is the handler routine. 

C- 

INTEGER*4 FUNCTION HANDLER ( SIGARGS, MECHARGS ) 

INTEGER*4 SIGARGS(*), STATUS 
INCLUDE '($SSDEF)' 

INCLUDE '($FORDEF)' 

INCLUDE '($CHFDEF)' 

RECORD /CHFDEF2/ MECHARGS 
HANDLER = SS$_CONTINUE 
C+ 

C This handler will type out an error message. In this case the 
C message is regarding a file open status. 

C- 

TYPE *, 'Entering handler...' 

STATUS = LIB$MATCH_COND ( SIGARGS (2) , FOR$_FILNOTFOU, 

1 FOR$ NO_SUCDEV, FOR$_FILNAMSPE, FOR$_OPEFAI ) 
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GOTO ( 100, 200, 300, 400 ) STATUS 
HANDLER = SS$_RESIGNAL 
GOTO 1000 

100 TYPE *, 'ERROR -- File not found' 

GOTO 1000 

200 TYPE *, 'ERROR — No such device' 

GOTO 1000 

300 TYPE *, 'ERROR — File name specification' 

GOTO 1000 

400 TYPE *, 'ERROR — Open failure' 

GOTO 1000 

C+ 

C On OpenVMS AXP systems use MECHARGS.CHF$IS_MCH_DEPTH 

C On OpenVMS VAX systems use MECHARGS.CHF$L_MCH_DEPTH 

C- 

1000 CALL SYS$UNWIND ( MECHARGS.CHF$IS_MCH_DEPTH , ) ! For OpenVMS AXP 

C 1000 CALL SYS$UNWIND ( MECHARGS.CHF$L_MCH_DEPTH , ) ! For OpenVMS VAX 
TYPE *, 'Returning from handler...' 

RETURN 

END 

This FORTRAN program uses a computed GOTO to alter the program execution 

sequence on a condition value. 

If the file called MATCH.DAT does not exist, the following output is returned: 

Establishing handler... 

Entering handler... 

ERROR — File not found 

Returning from handler... 

If the file MATCH.DAT does exist, the output returned is as follows: 

Establishing handler... 
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LIB$MOVC3—Move Characters 

The Move Characters routine makes the VAX MOVC3 1 instruction available as 
a callable routine. The source item is moved to the destination item. Overlap of 
the source and destination items does not affect the result. 


Format 


LIB$M0VC3 word-integer-length ,source destination 


Returns 


None. 


Arguments 

word-integer-length 

OpenVMS usage word_unsigned 
type word (unsigned) 

access read only 

mechanism by reference 

Number of bytes to be moved from source to destination by LIB$MOVC3. 
The word-integer-length argument is the address of an unsigned word which 
contains this number of bytes. The maximum transfer is 65,535 bytes. 


source 

OpenVMS usage 

type 

access 

mechanism 


unspecified 
unspecified 
read only 
by reference 


Item to be moved. The source argument is the address of this item. 


destination 

OpenVMS usage 

type 

access 

mechanism 


unspecified 
unspecified 
write only 
by reference 


Item into which source will be moved. The destination argument is the address 
of this item. 


Description 

LIB$MOVC3 is useful for moving large blocks of data, such as arrays, when such 
an operation would otherwise have to be performed by a programmed loop. 

For more information, see the VAX Architecture Reference Manual. See also 
OTS$MOVE3. 


1 On AXP systems, OpenVMS AXP instructions perform the equivalent operation. 
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Condition Values Returned 

None. 
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LIB$MOVC5—Move Characters with Fill 

The Move Characters with Fill routine makes the VAX MOVC5 1 instruction 
available as a callable routine. The source item is moved to the destination item. 
Overlap of the source and destination items does not affect the result. 


Format 


LIB$M0VC5 word-integer-source-length ,source [,fill] ,word-integer-destination-length destination 


Returns 


None. 


Arguments 

word-integer-source-length 

OpenVMS usage word_unsigned 
type word (unsigned) 

access read only 

mechanism by reference 

Number of bytes in the source item. The word-integer-source-length 
argument is the address of an unsigned word that contains this number of 
bytes. The maximum length of source is 65,535 bytes. 

source 

OpenVMS usage unspecified 
type unspecified 

access read only 

mechanism by reference 

Item to be moved by LIB$MOVC5. The source argument is the address of this 
item. If word-integer-source-length is zero, indicating that destination is to 
be entirely filled by the fill character, then source is ignored by LIB$MOVC5. 

fill 

OpenVMS usage byte_signed 
type byte integer (signed) 

access read only 

mechanism by reference 

Character used to pad source to the length of destination. The fill argument 
is the address of a signed byte integer that contains this fill character. If 

word-integer-destination-length is greater than or equal to word-integer- 
source-length, fill is unused and may be omitted. 

word-integer-destination-length 

OpenVMS usage word_unsigned 
type word (unsigned) 

access read only 

mechanism by reference 


1 On AXP systems, OpenVMS AXP instructions perform the equivalent operation. 
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Length of destination in bytes. The word-integer-destination-length 

argument is the address of an unsigned word that contains this number of 
bytes. The maximum value of word-integer-destination-length is 65,535 
bytes. 

destination 

OpenVMS usage unspecified 
type unspecified 

access write only 

mechanism by reference 

Item into which source will be moved. The destination argument is the address 
of this item. 


Description 

If the destination item is shorter than the source item, the highest-addressed 
bytes of the source are not moved. 

For more information, see the VAX Architecture Reference Manual. See also 
OTS$MOVE5. 

Condition Values Returned 

None. 
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LIB$MOVTC—Move Translated Characters 

The Move Translated Characters routine moves the source string, character by 
character, to the destination string after translating each character using the 
specified translation table. LIB$MOVTC makes the VAX MOVTC 1 instruction 
available as a callable routine. 

Format 

LIB$MOVTC source-string ,fill-character,translation-table .destination-string 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Arguments 

source-string 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Source string to be translated and moved by LIB$MOVTC. The source-string 
argument is the address of a descriptor pointing to this source string. 

fill-character 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Fill character used to pad source-string to the length of destination-string. 
The fill-character argument is the address of a descriptor pointing to a string. 
The first character of this string is used as the fill character. The length of this 
string is not checked and fill-character is not translated. 

translation-table 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Translation table used by LIB$MOVTC. The translation-table argument is the 
address of a descriptor pointing to the translation table string. The translation 
table string is assumed to be 256 characters long. 


1 On AXP systems, OpenVMS AXP instructions perform the equivalent operation. 


cond_value 
longword (unsigned) 
write only 
by value 
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You can use any one of the translation tables included in the Description section 
that follows, or you can create your own. When you use a translation table 
supplied by Digital, the names LIB$AB_xxx_yyy represent the addresses of the 
256-byte translation tables, and can be accessed as external (string) variables. If 
a particular language cannot generate descriptors for external strings, then you 
must create them manually. The example following the Description section shows 
the creation of a string descriptor for a translation table using VAX BASIC. 

destination-string 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor 

Destination string into which LIB$MOVTC writes the translated source-string. 
The destination-string argument is the address of a descriptor pointing to this 
destination string. 


Description 

Each character in the source string is used as an index into the translation table. 
The byte found is then placed into the destination string. The fill character is 
used if the destination string is longer than the source string. If the source string 
is longer than the destination string, the source string is truncated. Overlap of 
the source and destination strings does not affect execution. 

The translation tables used by LIB$MOVTC and LIB$MOVTUC are described 
below. Each table is preceded by explanatory text. 
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ASCII to EBCDIC Translation Table 

• The number on the left represents the low-order bits of the ASCII character 
in hexadecimal notation. 

• The number across the top represents the high-order bits of the ASCII 
character in hexadecimal notation. 

• The number in the body of the table represents the equivalent EBCDIC 
character in hexadecimal notation. 

Figure LIB-8 is the ASCII to EBCDIC Translation Table. 

Figure LIB-8 LIB$AB_ASC_EBC 
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ASCII to EBCDIC Reversible Translation Table 

• The number on the left represents the low-order bits of the ASCII character 
in hexadecimal notation. 

• The number across the top represents the high-order bits of the ASCII 
character in hexadecimal notation. 

• The number in the body of the table represents the equivalent EBCDIC 
character in hexadecimal notation. 

Figure LIB-9 is the ASCII to EBCDIC Reversible Translation Table. 

Figure LIB-9 LIB$AB_ASC_EBC_REV 
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EBCDIC to ASCII Translation Table 

• The number on the left represents the low-order bits of the EBCDIC character 
in hexadecimal notation. 

• The number across the top represents the high-order bits of the EBCDIC 
character in hexadecimal notation. 

• The number in the body of the table represents the equivalent ASCII 
character in hexadecimal notation. 

Figure LIB-10 is the EBCDIC to ASCII Translation Table. 

Figure LIB-10 LIB$AB_EBC_ASC 
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EBCDIC to ASCII Reversible Translation Table 

• The number on the left represents the low-order bits of the EBCDIC character 
in hexadecimal notation. 

• The number across the top represents the high-order bits of the EBCDIC 
character in hexadecimal notation. 

• The number in the body of the table represents the equivalent ASCII 
character in hexadecimal notation. 

Figure LIB-11 is the EBCDIC to ASCII Reversible Translation Table. 

Figure LIB-11 LIB$AB_EBC_ASC_REV 
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Packed Decimal to Trailing Overpunch Numeric Value Translation Table 

• The number on the left represents the low-order bits of the packed decimal 
value in hexadecimal notation. 

• The number across the top represents the high-order bits of the packed 
decimal value in hexadecimal notation. 

• The number in the body of the table represents the equivalent trailing 
overpunch numeric value in hexadecimal notation. 

Figure LIB-12 is the Packed Decimal to Trailing Overpunch Numeric Value 

Translation Table. 

Figure LIB-12 LIB$AB_CVTPT_Q 
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Packed Decimal to Unsigned Trailing Numeric Value Translation Table 

• The number on the left represents the low-order bits of the packed decimal 
value in hexadecimal notation. 

• The number across the top represents the high-order bits of the packed 
decimal value in hexadecimal notation. 

• The number in the body of the table represents the equivalent unsigned 
trailing numeric value in hexadecimal notation. 

Figure LIB-13 is the Packed Decimal to Unsigned Trailing Numeric Value 

Translation Table. 

Figure LIB-13 LIB$AB_CVTPT_U 
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Trailing Overpunch Numeric to Packed Decimal Value Translation Table 

• The number on the left represents the low-order bits of the trailing overpunch 
numeric value in hexadecimal notation. 

• The number across the top represents the high-order bits of the trailing 
overpunch numeric value in hexadecimal notation. 

• The number in the body of the table represents the equivalent packed decimal 
value in hexadecimal notation. 

Figure LIB—14 is the Trailing Overpunch Numeric to Packed Decimal Value 

Translation Table. 

Figure LIB-14 LIB$AB_CVTTP_Q 
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Unsigned Numeric to Packed Decimal Value Translation Table 

• The number on the left represents the low-order bits of the unsigned numeric 
value in hexadecimal notation. 

• The number across the top represents the high-order bits of the unsigned 
numeric value in hexadecimal notation. 

• The number in the body of the table represents the equivalent packed decimal 
value in hexadecimal notation. 

Figure LIB-15 is the Unsigned Numeric to Packed Decimal Value Translation 

Table. 

Figure LIB-15 LIB$AB_CVTTP_U 
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Trailing Overpunch Numeric to Unsigned Numeric Value Translation Table 

• The number on the left represents the low-order bits of the trailing overpunch 
numeric value in hexadecimal notation. 

• The number across the top represents the high-order bits of the trailing 
overpunch numeric value in hexadecimal notation. 

• The number in the body of the table represents the equivalent unsigned 
numeric value in hexadecimal notation. 

Figure LIB-16 is the Trailing Overpunch Numeric to Unsigned Numeric Value 

Translation Table. 

Figure LIB-16 LIB$AB_CVT_Q_U 
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Unsigned Numeric to Trailing Overpunch Translation Table 

Figure LIB-17 is indexed by 0 through 9 for the positive overpunches and 10 
through 19 for the negative overpunches. 

The unsigned binary representation of the least significant digit is moved into R2. 
Then, if you require a positive result, the following code results: 

MOVC3 LIB$AB_CVT_U_0[R2], #1,RO 

If you require a negative result, the following code is generated: 

MOVC3 LIB$AV_CVT_U_0 + 10[R2] f #1,R0 

The result is the overpunch representation for the last byte of the negative 
number. 

Figure LIB—17 is the Unsigned Numeric to Trailing Overpunch Translation 
Table. 

Figure LIB-17 LIB$AB_CVT_U_Q 
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Packed Decimal to Zone Numeric Translation Table 

• The number on the left represents the low-order bits of the packed decimal 
value in hexadecimal notation. 

• The number across the top represents the high-order bits of the packed 
decimal value in hexadecimal notation. 

• The number in the body of the table represents the equivalent zoned numeric 
value in hexadecimal notation. 

Figure LIB—18 is the Packed Decimal to Zone Numeric Translation Table. 

Figure LIB-18 LIB$AB_CVTPT_Z 
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Zone to Packed Decimal Translation Table 

• The number on the left represents the low-order bits of the zoned numeric 
value in hexadecimal notation. 

• The number across the top represents the high-order bits of the zoned 
numeric value in hexadecimal notation. 

• The number in the body of the table represents the equivalent packed value 
decimal value in hexadecimal notation. 

Figure LIB-19 is the Zone to Packed Decimal Translation Table. 

Figure LIB-19 LIB$AB_CVTTP_Z 
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ASCII Uppercase Translation Table 

• The number on the left represents the low-order bits of the ASCII character 
in hexadecimal notation. 

• The number across the top represents the high-order bits of the ASCII 
character in hexadecimal notation. 

• The number in the body of the table represents the equivalent uppercase 
ASCII character in hexadecimal notation. 

Figure LIB-20 is the ASCII Uppercase Translation Table. 

Figure LIB-20 LIB$AB_UPCASE 
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ASCII Lowercase Translation Table 

• The number on the left represents the low-order bits of the ASCII character 
in hexadecimal notation. 

• The number across the top represents the high-order bits of the ASCII 
character in hexadecimal notation. 

• The number in the body of the table represents the equivalent lowercase 
ASCII character in hexadecimal notation. 

Figure LIB—21 is the ASCII Lowercase Translation Table. 

Figure LIB-21 LIB$AB_LOWERCASE 
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Condition Values Returned 

SS$_N ORMAL 
LIB$_STRTRU 


LIB$_FATERRLIB 

LIB$_INSVIRMEM 

LIB$_INVSTRDES 


Routine successfully completed. 

Routine successfully completed; string truncated. 
The fixed-length destination string could not 
contain all the characters. 

Fatal internal error. 

Insufficient virtual memory. 

Invalid string descriptor. 


Example 


1 ! + 

!This BASIC program shows the method 

!of creating a descriptor for the appropriate 

I translation table in order to call LIB$MOVTC. 

i _ 

OPTION TYPE = EXPLICIT 
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i + 

!Declare the translation table as an 
!EXTERNAL LONG variable. 


EXTERNAL LONG LIB$AB_ASC_EBC 
EXTERNAL LONG FUNCTION LIB$MOVTC 
EXTERNAL SUB LIB$STOP 

EXTERNAL LONG CONSTANT DSC$K_CLASS_S, DSC$K_DTYPE_T 
! + 

!Define a record which models the required 
!translation table descriptor. 

i _ 

RECORD STR_TYPE 

WORD DSC$W_LENGTH 

BYTE DSC$B_DTYPE 

BYTE DSC$B_CLASS 

LONG DSC$A_POINTER 

END RECORD STR_TYPE 

DECLARE LONG I, RET_STS 
DECLARE STR_TYPE STR_VAR 

MAP (FOO) STRING DST = 3% 

MAP (FOO) BYTE DST_ARRAY(2) 

! + 

!Fill the translation table descriptor record. 

!Note that the length of the translation table string 
!is set to 256, and the pointer receives the address of 
!the Digital translation table LIB$AB_ASC_EBC. 

i _ 


STR_VAR::DSC$W_LENGTH = 256 
STR_VAR::DSC$B_DTYPE = DSC$K_DTYPE_T 
STR__VAR: :DSC$B_CLASS = DSC$K_CLASS_S 
STR_VAR::DSC$A_POINTER = LOC(LIB$AB_ASC_EBC) 

RET_STS = LIB$MOVTC( "ABC", " ", STR_VAR BY REF, DST ) 
IF (RET_STS AND 1%) = 0% 

THEN 

CALL LIB$STOP( RET_STS BY VALUE ) 

END IF 

! + 

!Add 256 to the translated value in order to return 
!an unsigned value. 

i _ 

PRINT (256 + DST_ARRAY(I)) FOR I = 0% TO 2% 

END 

The output generated by this BASIC program is as follows: 

193 

194 

195 
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UB$MOVTUC—Move Translated Until Character 

The Move Translated Until Character routine moves the source string, character 
by character, to the destination string after translating each character using the 
specified translation table until the stop character is encountered. LIB$MOVTUC 
makes the VAX MOVTUC 1 instruction available as a callable routine. 


Format 


Returns 


LIB$MOVTUC source-string ,stop-character,translation-table ,destination-string [.fill-character] 


OpenVMS usage longword_unsigned 
type longword (unsigned) 

access write only 

mechanism by value 

The relative position in the source string of the character that is translated to the 
stop character. Zero is returned if the stop character is not found. This value is 
set to —1 if destination-string cannot be allocated. 


Arguments 

source-string 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Source string to be translated and moved by LIB$MOVTUC. The source-string 
argument is the address of a descriptor pointing to this source string. 

stop-character 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Stop character that causes LIB$MOVTUC to stop translating the source string. 
The stop-character argument is the address of a descriptor pointing to a string. 
The first character of this string is used as the stop character. The length of 
this string is not checked. During the translation, LIB$MOVTUC accesses each 
character in the source string and uses it as an index into the translation table. 
If this translated character is the specified stop character, then translation stops, 
and stop-character is not translated. 

translation-table 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 


1 On AXP systems, OpenVMS AXP instructions perform the equivalent operation. 
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Translation table used by LIB$MOVTUC. The translation-table argument is the 
address of a descriptor pointing to the translation table string. The translation 
table string is assumed to be 256 characters long. 

You can use any of the translation tables included in the Description section 
of LIB$MOVTC, or you can create your own. When using a translation table 
supplied by Digital, the names LIB$AB_xxx_yyy represent the addresses of the 
256 byte translation tables, and can be accessed as external (string) variables. If 
a particular language cannot generate descriptors for external strings, then they 
must be created manually. The example for the routine LIB$MOVTC shows the 
creation of a string descriptor for a translation table using VAX BASIC. 


destination-string 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor 

Destination string into which LIB$MOVTUC writes the translated source¬ 
string. The destination-string argument is the address of a descriptor pointing 
to this destination string. 


fill-character 

OpenVMS usage 

type 

access 

mechanism 


char_string 
character string 
read only 
by descriptor 


Character used to pad source-string to the length of destination-string. The 
fill-character argument is the address of a descriptor pointing to a string. The 
first character of this string is used as the fill character. The length of this string 
is not checked and fill-character is not translated. 


If the fill character is included, the remainder of the destination string (after the 
stop character) is filled with the specified fill character. If it is not included, the 
remainder of the destination string remains unchanged. 


Description 

During the translation, LIB$MOVTUC accesses each character in the source 
string and uses it as an index into the translation table. If the table entry 
contains the specified stop character, the routine is terminated and the relative 
position of the source character is returned. 

If the source string is longer than the destination string, then the source string is 
truncated. If the optional fill character is present, any remaining positions in the 
destination string are filled with the fill character. If the source or destination 
string is exhausted (before the stop character is found), a zero index is returned. 

The results are unpredictable if the source and destination strings overlap and 
have different starting addresses. 

See the description of LIB$MOVTC for the translation tables used by 
LIB$MOVTC and LIB$MOVTUC. Each translation table is preceded by 
explanatory text. 
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Condition Values Returned 

None. 
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LIB$MULT_DELTA_TIME—Multiply Delta Time by Scalar 

The Multiply Delta Time by Scalar routine multiplies a delta time by a longword 
integer scalar. 

Format 

UB$MULT_DELTA_TIME multiplier .delta-time 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Arguments 

multiplier 

OpenVMS usage longword_signed 
type longword (signed) 

access read only 

mechanism by reference 

The value by which LIB$MULT_DELTA_TIME multiplies the delta time. The 
multiplier argument is the address of a signed longword containing the integer 
scalar. If multiplier is negative, the absolute value of multiplier is used. 

delta-time 

OpenVMS usage date_time 
type quadword (unsigned) 

access modify 

mechanism by reference 

The delta time to be multiplied. The delta-time argument is the address of 
an unsigned quadword containing the number to be multiplied. Delta-time 
must be less than 10,000 days. After LIB$MULT_DELTA_TIME performs the 
multiplication, the result is returned to delta-time. (The original delta-time is 
overwritten.) 

Description 

LIB$MULT_DELTA_TIME multiplies a delta time by a longword integer scalar. 
The result of the multiplication is returned to the delta-time argument. 

Condition Values Returned 

LIB$_NORMAL Normal successful completion. 

LIB$_IVTIME Invalid time. 

LIB$_WRONUMARG Incorrect number of arguments. 


cond_value 
longword (unsigned) 
write only 
by value 
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LIB$MULTF_DELTA_TIME—Multiply Delta Time by an F_Floating 

Scalar 

The Multiply Delta Time by an F-Floating Scalar routine multiplies a delta time 
by an F-floating scalar. 

Format 

LIB$MULTF_DELTA_TIME multiplier ,delta-time 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Arguments 

multiplier 

OpenVMS usage floating_point 
type F_floating 

access read only 

mechanism by reference 

The value by which LIB$MULTF_DELTA_TIME multiplies the delta time. The 
multiplier argument is the address of an F-floating value containing the scalar. 
If multiplier is negative, the absolute value of multiplier is used. 

delta-time 

OpenVMS usage date_time 
type quadword (unsigned) 

access modify 

mechanism by reference 

The delta time to be multiplied. The delta-time argument is the address of 
an unsigned quadword containing the number to be multiplied. Delta-time 
must be less than 10,000 days. After LIB$MULTF_DELTA_TIME performs the 
multiplication, the result is returned to delta-time. (The original delta-time is 
overwritten.) 

Description 

LIB$MULTF_DELTA_TIME multiplies a delta time by an F-floating scalar. The 
result of the multiplication is returned to the delta-time argument. 

Condition Values Returned 

LIB$_NORMAL Normal successful completion. 

LIB$_IVTIME Invalid time. 

LIB$_WRONUMARG Incorrect number of arguments. 


cond_value 
longword (unsigned) 
write only 
by value 
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LIB$PARSE_ACCESS_CODE— Parse Access Encoded Name String 


On VAX systems, the Parse Access Encoded Name String routine parses and 
translates a string of access names into a mask for a particular ownership 
category. 


Format 


LIB$PARSE_ACCESS_CODE access-string, [access-names,] ownership-category, access-mask, 

[end-position] 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Arguments 


access-string 

OpenVMS usage 

type 

access 

mechanism 


char_string 

character-coded text string 
read only 
by descriptor 


The access-string argument is the address of a character string descriptor 
pointing to a string of access names. Each access name is abbreviated to one 
letter. An example of a valid access-string is RWE. Access names are specific 
to each of the different object classes. See the OpenVMS VAX Guide to System 
Security for a complete list of all valid access names. 


access-names 

OpenVMS usage access_names 

type array [0..31] of quadword string descriptor 

access read only 

mechanism by reference 

The access-names argument is the address of the access name table for the 
associated object class. For example, it is the value returned by the LIB$GET_ 
ACCNAM routine in the accnam longword. This parameter is optional and 
defaults to the access name table for the FILE object class. 

ownership-category 

OpenVMS usage mask_word 
type word (unsigned) 

access read only 

mechanism by reference 

The ownership-category argument is the address of a word that indicates the 
ownership category the access names refer to. 

• 0000000000001111 - System 

• 0000000011110000 - Owner 
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• 0000111100000000 - Group 

• 1111000000000000 - World 

access-mask 

OpenVMS usage mask_word 
type word (unsigned) 

access write only 

mechanism by reference 

The access-mask argument is the address of a word into which this routine 
writes the access mask. In this mask, a set bit means the access was requested 
for the specified ownership. Note that this is the opposite of the standard 
protection format where a set bit means no access. 

end-position 

OpenVMS usage word_signed 
type word (signed) 

access write only 

mechanism by reference 

The end-position argument is the number of characters from access-string 
processed by LIB$PARSE_ACCESS_CODE. In the case of an error in parsing the 
access string, the offset to the offending location is returned. 


Description 

LIB$PARSE_ACCESS_CODE parses a string of access names and translates 
the string into a mask for the requested ownership category. The string is a 
concatenated list of one-letter abbreviations of access names. 

This routine works for any protected object class by specifying the correct access 
name table. The address of the access name table can be obtained from the 
LIB$GET_ACCNAM routine. 

This routine is useful for building a protection mask where the ownership names 
have already been parsed. Use LIB$PARSE_SOGW_PROT for parsing a string 
containing both ownership and access names. 

The mask returned has bits set for the access requested for the specified 
ownership. This is opposite the standard protection format where a set bit in 
the protection mask means no access. 

The number of characters processed is optionally returned. This is useful for 
error processing. The end-position will be the offset to the character that made 
the access category name-string invalid. 

Condition Values Returned 

SS$_NORMAL Normal successful completion. 

LIB$_IVARG Required parameter missing or a character in 

access-string did not represent a valid access 
type. 

LIB$_WRONGNUMARG Wrong number of arguments. ♦ 
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LIB$PARSE_SOGW_PROT— Parse Protection String 



On VAX systems, the Parse Protection String routine parses and translates a 
protection string into a protection mask. 


Format 


UB$PARSE_SOGW_PROT protection-string, [access-names], protection-mask, ownership-mask, 
[end-position] 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Arguments 


protection-string 

OpenVMS usage 

type 

access 

mechanism 


char_string 

character-coded text string 
read only 
by descriptor 


The protection-string argument is the address of a character string descriptor 

pointing to the protection string. The string components are: 

• Ownership name - System,Owner,Group,World. Ownership names can be 
specified in full, or truncated to any number of characters. Matching is case 
blind and spacing is ignored. 

• Access name - Access names are always abbreviated to one letter. For 
example, access names for files are R (for read), W (for write), E (for edit), 
and D (for delete). Any combination can be passed. For example, RWE is a 
valid combination. A null access name specification means no access. 

• Separators - Access names are separated from ownership names by either 
a colon (:) or an equal sign (=). The comma (,) is the list separator. A null 
access name specification means no access. 

An example of a valid protection string is: 

SYSTEM=RWED ,OWNER:RWED, GROUP,WORLD: R 


access-names 

OpenVMS usage access_names 

type array [0..31] of quadword string descriptor 

access read only 

mechanism by reference 

The access-names argument is the address of the access name table for the 
associated object class. For example, it is the value returned by the LIB$GET 
ACCNAM routine in the accnam longword. This parameter is optional and 
defaults to the access name table for the FILE object class. 
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protection-mask 

OpenVMS usage protection 
type word (unsigned) 

access write only 

mechanism by reference 

The protection-mask argument is the address of a word into which this routine 
writes a 16-bit protection mask translation of the protection string. Each bit set 
in the mask indicates no access for the access type it represents. 

ownership-mask 

OpenVMS usage mask_word 
type word (unsigned) 

access write only 

mechanism by reference 

The ownership-mask argument is the address of a word that indicates which 
ownership names were present in the protection string. 

• 0000000000001111 - System 

• 0000000011110000 - Owner 

• 0000111100000000 - Group 

• 1111000000000000 - World 

end-position 

OpenVMS usage word_signed 
type word (signed) 

access write only 

mechanism by reference 

The end-position argument is the number of characters from protection-string 
processed by LIB$PARSE_SOGW_PROT. In the case of an error in parsing the 
protection string, the offset to the offending location is returned. 

Description 

LIB$PARSE_SOGW_PROT parses a protection string and translates the string 
into a 16 bit protection mask. LIB$PARSE_SOGW_PROT works for any protected 
object class by specifying the correct access name table. 

The address of the access name table can be obtained from the LIB$GET_ 
ACCNAM routine. Note that file access names are valid for any protected object 
class. 

The number of characters processed is optionally returned. This is useful in error 
processing. The end-position will be the offset to the character that made the 
protection string invalid. Note that the entire protection string must be valid or 
an error will be returned. 

Several scenarios can cause the protection string to be invalid. The format of the 
protection string may be invalid, or the access category abbreviations may not be 
valid with respect to the access name tables. 
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Condition Values Returned 

SS$_N ORMAL 
LIB$_IVARG 

LIB$_WRONGNUMARG 


Normal successful completion. 

Required parameter missing or invalid protection 
string. 

Wrong number of arguments. ♦ 
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LIB$PAUSE—Pause Program Execution 

The Pause Program Execution routine suspends program execution and returns 
control to the calling command level. 


Format 

LIB$PAUSE 


Returns 

cond_value 
longword (unsigned) 
write only 
by value 

Arguments 

None. 


OpenVMS usage 

type 

access 

mechanism 


Description 

LIB$PAUSE suspends program execution and returns control to the calling 
command level. The suspended image may be continued with the CONTINUE 
command, or it may be terminated with the EXIT or STOP commands. In the 
latter case, the image will not return to this routine. 

Note that this routine functions only for interactive jobs. If this routine is invoked 
in batch mode, it has no effect. 


Condition Values Returned 


SS$_N ORMAL 
LIB$_NOCLI 


Normal successful completion. 

No CLI present. The calling process does not 
have a CLI or the CLI does not support the 
request. Note that DCL only supports this 
function in INTERACTIVE mode. 
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LIB$POLYD—Evaluate Polynomials 


AXP 


Format 


The Evaluate Polynomials routine (D-floating point values) allows higher-level 
language users to evaluate D-floating point value polynomials. 

D-floating point values are not supported in full precision in native OpenVMS 
AXP programs. They are precise to 56 bits on VAX systems, 53 or 56 bits in 
translated VAX images, and 53 bits in native OpenVMS AXP programs. ♦ 


LIB$POLYD polynomial-argument ,degree coefficient .floating-point-result 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 


Arguments 

polynomial-argument 

OpenVMS usage floating_point 
type D_floating 

access read only 

mechanism by reference 

Argument for the polynomial. The polynomial-argument argument is 
the address of a floating-point number that contains this argument. The 
polynomial-argument argument is a D-floating number. 

degree 

OpenVMS usage word_signed 
type word integer (signed) 

access read only 

mechanism by reference 

Highest numbered nonzero coefficient to participate in the evaluation. The 
degree argument is the address of a signed word integer that contains this 
highest-numbered coefficient. 

If the degree is 0, the result equals C[0]. The range of the degree is 0 to 31. 

coefficient 

OpenVMS usage floating_point 

type D_floating 

access read only 

mechanism by reference, array reference 

Floating-point coefficients. The coefficient argument is the address of an 
array of floating-point coefficients. The coefficient of the highest-order term of 
the polynomial is the lowest-addressed element in the array. The coefficient 
argument is an array of D-floating numbers. 
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floating-point-result 

OpenVMS usage floating_point 
type D_floating 

access write only 

mechanism by reference 

Result of the calculation. The floating-point-result argument is the address of 
a floating-point number that contains this result. LIB$POLYD writes the address 
of floating-point-result into a D-floating number. 

Intermediate multiplications are carried out using extended floating-point 
fractions (63 bits for POLYD). 


Description 

LIB$POLYD provides higher-level language users with the capability of 
evaluating polynomials. 

The evaluation is carried out by Horner’s Method. The result is computed as 
follows: 

result = C[0]+X*(C[1]+X*(C[2]+...X*(C[D])...)) 

In the above result D is the degree of the polynomial and X is the argument. 

See the VAX Architecture Reference Manual for the detailed description of POLY. 


Condition Values Returned 

SS$_N ORMAL 

SS$_FLTOVF 

SS$_ROPRAND 


Routine successfully completed. 
Floating overflow. 

Reserved operand. 


Example 


The FORTRAN and Pascal examples provided in the description of LIB$POLYF 
also demonstrate how to use LIB$POLYD. Please refer to those examples for 
assistance in using this routine. 
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LIB$POLYF—Evaluate Polynomials 

The Evaluate Polynomials routine (F-floating point values) allows higher-level 
language users to evaluate F-floating point polynomials. 


Format 

LIB$POLYF polynomial-argument ,degree coefficient .floating-point-result 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Arguments 

polynomial-argument 

OpenVMS usage floating_point 
type F_floating 

access read only 

mechanism by reference 

Argument for the polynomial. The polynomial-argument argument is 
the address of a floating-point number that contains this argument. The 
polynomial-argument argument is an F-floating number. 

degree 

OpenVMS usage word_signed 
type word (signed) 

access read only 

mechanism by reference 

Highest numbered nonzero coefficient to participate in the evaluation. The 
degree argument is the address of a signed word integer that contains this 
highest-numbered coefficient. 

If the degree is 0, the result equals C[0]. The range of the degree is 0 to 31. 

coefficient 

OpenVMS usage floating_point 

type F_floating 

access read only 

mechanism by reference, array reference 

Floating-point coefficients. The coefficient argument is the address of an 
array of floating-point coefficients. The coefficient of the highest-order term of 
the polynomial is the lowest-addressed element in the array. The coefficient 
argument is an array of F-floating numbers. 

floating-point-result 

OpenVMS usage floating_point 
type F_floating 

access write only 

mechanism by reference 
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Result of the calculation. The floating-point-result argument is the address of 
a floating-point number that contains this result. LIB$POLYF writes the address 
of floating-point-result into an F-floating number. 

Intermediate multiplications are carried out using extended floating-point 
fractions (31 bits for POLYF). 


Description 

LIB$POLYF provides higher-level language users with the capability of 
evaluating polynomials. 

The evaluation is carried out by Horner’s Method. The result is computed as 
follows: 

result = C[0]+X*(C[1]+X*(C[2] + X*(C[D])...)) 

In the above result D is the degree of the polynomial and X is the argument. 


Condition Values Returned 

SS$_N ORMAL 

SS$_FLTOVF 

SS$_ROPRAND 


Normal successful completion 
Floating overflow. 

Reserved operand. 


Examples 


i. c+ 

' C This FORTRAN example demonstrates how to use 
C LIB$POLYF. 

C- 


REAL*4 X,COEFF(5),RESULT 
INTEGERS DEG 

C+ 

C Compute X A 4 + 2*X A 3 -X A 2 + X - 3 using POLYF. 
C Let X = 2. 

C The coefficients needed are as follows: 

C- 


DATA COEFF/1.0,2.0,-1.0,1.0,-3.0/ 

X = 2.0 

DEG = 4 1 DEG has word length. 


C+ 

C Calculate (2) A 4 + 2*(2 A 3) -2 A 2 +2-3. 
C The result should be 27. 

C- 


RETURN = LIB$POLYF(X,DEG,COEFF,RESULT) 

TYPE *, '(2 ) A 4 + 2*(2 A 3 ) -2 A 2 + 2 - 3 = ' ,RESULT 
END 

This FORTRAN example demonstrates how to call LIB$POLYF. The output 
generated by this program is as follows: 

(2) A 4 + 2*(2 A 3) -2 A 2 + 2 - 3 = 27.00000 
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2. PROGRAM POLYP(INPUT,OUTPUT); 

{ + } 

{ This Pascal program demonstrates how to use 
{ LIB$POLYF to evaluate a polynomial. 

{-} 

TYPE 

WORD = [WORD] 0..65535; 

VAR 

COEFF : ARRAY [0..2] OF REAL := (1.0,2.0,2.0); 

RESULT : REAL; 

RETURNED_STATUS : INTEGER; 

[EXTERNAL] FUNCTION LIB$POLYF( 

ARG : REAL; 

DEGREE : WORD; 

COEFF : [REFERENCE] ARRAY [L..U:INTEGER] OF REAL; 

VAR RESULT : REAL 

) : INTEGER; EXTERNAL; 

[EXTERNAL] FUNCTION LIB$STOP( 

CONDITION_STATUS : [IMMEDIATE,UNSAFE] UNSIGNED; 
FAO_ARGS : [IMMEDIATE,UNSAFE,LIST] UNSIGNED 

) : INTEGER; EXTERNAL; 


BEGIN 
{ + } 

{ Call LIB$POLYF to evaluate 2(X**2) + 2*X + 1. 

{-} 

RETURNED_STATUS := LIB$POLYF(1.0,2,COEFF,RESULT); 

IF NOT ODD(RETURNED_STATUS) 

THEN 

LIB$STOP(RETURNED_STATUS); 

WRITELN(' F (1.0 ) = ',RESULT:5:2); 

END. 

This example program demonstrates how to call LIB$POLYF from Pascal. 
The output generated by this Pascal program is as follows: 

$ RUN POLYF 
F(1.0) = 5.00 
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LIB$POLYG—Evaluate Polynomials 


The Evaluate Polynomials routine (G-floating point values) allows higher-level 
language users to evaluate G-floating point value polynomials. 


Format 


Returns 


LIB$POLYG polynomial-argument .degree .coefficient .floating-point-result 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 


Arguments 

polynomial-argument 

OpenVMS usage floating_point 
type G_floating 

access read only 

mechanism by reference 

Argument for the polynomial. The polynomial-argument argument is 
the address of a floating-point number that contains this argument. The 
polynomial-argument argument is a G-floating number. 

degree 

OpenVMS usage word_signed 
type word integer (signed) 

access read only 

mechanism by reference 

Highest numbered nonzero coefficient to participate in the evaluation. The 
degree argument is the address of a signed word integer that contains this 
highest-numbered coefficient. 

If the degree is 0, the result equals C[0]. The range of the degree is 0 to 31. 

coefficient 

OpenVMS usage floating_point 

type G_floating 

access read only 

mechanism by reference, array reference 

Floating-point coefficients. The coefficient argument is the address of an 
array of floating-point coefficients. The coefficient of the highest-order term of 
the polynomial is the lowest-addressed element in the array. The coefficient 
argument is an array of G-floating numbers. 

floating-point-result 

OpenVMS usage floating_point 
type G_floating 

access write only 

mechanism by reference 
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Result of the calculation. The floating-point-result argument is the address of 
a floating-point number that contains this result. LIB$POLYG writes the address 
of floating-point-result into a G-floating number. 

Intermediate multiplications are carried out using extended floating-point 
fractions (63 bits for POLYG). 


Description 

LIB$POLYG provides higher-level language users with the capability of 
evaluating polynomials. 

The evaluation is carried out by Horner’s Method. The result is computed as 
follows: 

result = C[0]+X*(C[1]+X*(C[2]+...X*(C[D])...)) 

In the above result D is the degree of the polynomial and X is the argument. 

Condition Values Returned 

SS$_NORMAL Routine successfully completed. 

SS$_FLTOVF Floating overflow. 

SS$_ROPRAND Reserved operand. 


Example 

The FORTRAN and Pascal examples provided in the description of LIB$POLYF 
also demonstrate how to use LIB$POLYG. Please refer to those examples for 
assistance in using this routine. 
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LIB$POLYH—Evaluate Polynomials 


AXP 


On OpenVMS VAX systems, the Evaluate Polynomials routine (H-floating point 
values) allows higher-level language users to evaluate H-floating point value 
polynomials. 

This routine is not available to native OpenVMS AXP programs, but is available 
to translated VAX images. ♦ 


Format 

UB$POLYH polynomial-argument .degree .coefficient .floating-point-result 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 


Arguments 

polynomial-argument 

OpenVMS usage floating_point 
type H_floating 

access read only 

mechanism by reference 

Argument for the polynomial. The polynomial-argument argument is 
the address of a floating-point number that contains this argument. The 
polynomial-argument argument is an H-floating number. 

degree 

OpenVMS usage word_signed 
type word integer (signed) 

access read only 

mechanism by reference 

Highest numbered nonzero coefficient to participate in the evaluation. The 
degree argument is the address of a signed word integer that contains this 
highest-numbered coefficient. 

If the degree is 0, the result equals C[0]. The range of the degree is 0 to 31. 

coefficient 

OpenVMS usage floating_point 

type H_floating 

access read only 

mechanism by reference, array reference 

Floating-point coefficients. The coefficient argument is the address of an 
array of floating-point coefficients. The coefficient of the highest-order term of 
the polynomial is the lowest-addressed element in the array. The coefficient 
argument is an array of H-floating numbers. 
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floating-point-result 

OpenVMS usage floating_point 
type H_floating 

access write only 

mechanism by reference 

Result of the calculation. The floating-point-result argument is the address of 
a floating-point number that contains this result. LIB$POLYH writes the address 
of floating-point-result into an H-floating number. 

Intermediate multiplications are carried out using extended floating-point 
fractions (127 bits for POLYH). 


Description 

LIB$POLYH provides higher-level language users with the capability of 
evaluating polynomials. 

The evaluation is carried out by Horner’s Method. The result is computed as 
follows: 

result = C[0]+X*(C[1]+X*(C[2]+...X*(C[D])...)> 

In the above result D is the degree of the polynomial and X is the argument. 


Condition Values Returned 

SS$_NORMAL 

SS$_FLTOVF 

SS$_ROPRAND 


Routine successfully completed 
Floating overflow. 

Reserved operand. 


Example 


The FORTRAN and Pascal examples provided in the description of LIB$POLYF 
also demonstrate how to use LIB$POLYH. Please refer to those examples for 
assistance in using this routine. 
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LIB$PUT_COMMON—Put String to Common 

The Put String to Common routine copies the contents of a string into the 
common area. The common area is an area of storage which remains defined 
across multiple image activations in a process. Optionally, LIB$PUT_COMMON 
returns the actual number of characters copied. The maximum number of 
characters that can be copied is 252. 


Format 

LIB$PUT_COMMON source-string [,resultant-length] 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Arguments 


source-string 

OpenVMS usage 

type 

access 

mechanism 


char_string 
character string 
read only 
by descriptor 


Source string to be copied to the common area by LIB$PUT_COMMON. The 
source-string argument is the address of a descriptor pointing to this source 
string. 


resultant-length 

OpenVMS usage word_unsigned 
type word (unsigned) 

access write only 

mechanism by reference 

Number of characters copied by LIB$PUT_COMMON to the common area. The 
resultant-length argument is the address of an unsigned word integer that 
contains this number of characters. LIB$PUT_COMMON writes this number into 
the resultant-length argument. 


Description 

LIB$PUT_COMMON and LIB$GET_COMMON allow programs to copy strings to 
and from the common area. The programs reading and writing the data in the 
common area must agree upon its amount and format. The maximum length of 
the destination string is defined as follows: 

[min(256, the length of the data in the common storage area) - 4] 

Thus, maximum length is 252. 
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In BASIC and FORTRAN, you can use these routines to allow a USEROPEN 
routine to pass information back to the routine that called it. A USEROPEN 
routine cannot write arguments. However, it can call LIB$PUT_COMMON to put 
information into the common area. The calling program can then use LIB$GET_ 
COMMON to retrieve it. 

You can also use these routines to pass information between images run 
successively, such as chained images run by LIB$RUN_PROGRAM. Since the 
common area is unique to each process, do not use LIB$GET_COMMON and 
LIB$PUT_COMMON to share information across processes. 


Condition Values Returned 

SS$_N ORMAL 
LIB$_STRTRU 

LIB$_FATERRLIB 


LIB$_INSVIRMEM 

LIB$_INVSTRDES 


Routine successfully completed. 

Successfully completed, but the source string was 
truncated. 

Fatal internal error. An internal consistency 
check has failed. This usually indicates an 
internal error in the Run-Time Library and 
should be reported to Digital in a Software 
Performance Report (SPR). 

Insufficient virtual memory. A call to LIB$GET_ 
VM has failed because your program has 
exceeded the image quota for virtual memory. 

Invalid string descriptor. A string descriptor has 
an invalid value in its DSC$B_CLASS field. 
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LIB$PUT_INVO_REGISTERS — Put Invocation Registers 

The Put Invocation Registers routine updates a given procedure invocation 
context’s fields with new register contents. 


Format 


Returns 


LIB$PUT_INVO_REGISTERS invo_handle, invo_context, invojmask 


OpenVMS usage longword_unsigned 
type longword (unsigned) 

access write only 

mechanism by value 

Status value. A value of 1 indicates success. When the initial context represents 
the bottom of the call chain, a value of 0 is returned. 


Arguments 

invo_handle 

OpenVMS usage invo_handle 
type longword (unsigned) 

access read only 

mechanism by value 

Handle for the invocation to be updated. 

invo_context 

OpenVMS usage invo_context_blk 
type structure 

access read only 

mechanism by reference 

Address of an invocation context block that contains new register contents. 

Each register that is set in the invojmask parameter is updated using the 
value found in the corresponding IREG or FREG field. The program counter and 
processor status of the given invocation can also be updated in this way. No other 
fields of the invocation context block are used. 

invo_mask 

OpenVMS usage mask_quadword 
type quadword (unsigned) 

access read only 

mechanism by reference 

Address of a 64-bit vector, where each bit corresponds to a register field in 
the passed invo_context. Bits 0 through 30 correspond to IREG[0] through 
IREG[30], bit 31 corresponds to PROGRAM_COUNTER, bits 32 through 
62 correspond to FREG[0] through FREG[30], and bit 63 corresponds to 
PROCESSOR_STATUS. 
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Description 

LIB$PUT_INVO_REGISTERS updates a given procedure invocation context’s 
fields with new register contents. 

See the OpenVMS Calling Standard manual for additional information. 

Condition Values Returned 

None. 
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LIB$PUT_OUTPUT—Put Line to SYS$OUTPUT 

The Put Line to SYS$OUTPUT routine writes a record to the current controlling 
output device, specified by SYS$OUTPUT using the RMS $PUT service. 


Format 

LIB$PUT_OUTPUT message-string 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Argument 


message-string 

OpenVMS usage 

type 

access 

mechanism 


char_string 
character string 
read only 
by descriptor 


Message string written to the current controlling output device by LIB$PUT_ 
OUTPUT. The message-string argument is the address of a descriptor pointing 
to this message string. RMS handles all formatting, so the message does not need 
to include such ASCII formatting instructions as carriage return (CR). 


Description 

When you log in, OpenVMS operating systems create three files as default I/O 
control streams for your process. 

• SYS$INPUT, your default input device 

• SYS$OUTPUT, your default output device 

• SYS$COMMAND, the device that supplies the commands to your process 

These files remain open until you log out. They are the interface between your 
interactive input and output or batch commands and the OpenVMS software. 
Initially, all three are equated with the terminal. However, with the DCL 
ASSIGN command, you can change these assignments to obtain information 
from a file or put information into a file. SYS$INPUT and SYS$COMMAND 
are usually identical, but the input and command streams can be different. For 
example, during the execution of an indirect command file from an interactive 
terminal, SYS$COMMAND refers to the terminal and SYS$INPUT refers to the 
command file. 

On the first call to LIB$PUT_OUTPUT, if the output file is not a process- 
permanent file, LIB$PUT_OUTPUT opens the output file and positions it at 
the end-of-file mark. If no output file exits on the first call, LIB$PUT_OUTPUT 
creates a file. The RMS internal stream identifier (ISI) is stored in the routine’s 
static storage for subsequent calls. Hence, this routine is not AST reentrant. 
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LIB$PUT_OUTPUT uses RMS to format records on output, and RMS records 
have implied carriage control. That is, a record normally corresponds to a line of 
text. Therefore, if you want explicit carriage control, instead of implied carriage 
control, you must supply it yourself within the source string. 

LIB$PUT_OUTPUT is the most convenient way for a MACRO or BLISS program 
to write information to SYS$OUTPUT. 

If you have several shareable images that call LIB$PUT_OUTPUT, and if each 
shareable image includes its own copy of LIB$PUT_OUTPUT, your program could 
produce multiple output streams and multiple versions of your output file. A 
single application should reference one copy of LIB$PUT_OUTPUT. 

Condition Values Returned 

SS$_NORMAL Routine successfully completed. 

Any condition values returned by RMS. 


Example 


10 ! + 

! This BASIC program demonstrates how to use 
! LIB$PUT_OUTPUT to output a simple message. 

i _ 

MSGSTR$ = 'This is a sample message' 

CALL LIB$PUT_OUTPUT(MSGSTR$) 

! + 

! In this example, the default value of 
! SYS$OUTPUT is used. Therefore, the 
! output is 'put' to the terminal screen. 

90 END 

This BASIC program shows the use of LIB$PUT_OUTPUT. The output generated 
by this BASIC example is as follows: 

This is a sample message 
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LIB$RADIX_POINT—Radix Point Symbol 

The Radix Point Symbol routine returns the system’s radix point symbol. 

This symbol is used inside a digit string to separate the integer part from the 
fraction part. This routine works by attempting to translate the logical name 
SYS$RADIX_POINT as a process, group, or system logical name. 

Format 

LIB$RADIX_POINT radix-point-string [,resultant-length] 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Arguments 

radix-point-string 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor 

Radix point string. The radix-point-string argument is the address of a 
descriptor pointing to this radix point string. 

resultant-length 

OpenVMS usage word_unsigned 
type word (unsigned) 

access write only 

mechanism by reference 

The number of characters written into radix-point-string, not counting padding 
in the case of a fixed-length string. The resultant-length argument is the 
address of an unsigned word that contains this number. 

If the radix-point-string argument is the address of a fixed-length string 
descriptor, there may not be enough characters in the fixed-length string to 
contain the whole radix point string, and the radix point string is truncated. 

If the radix point string is truncated to the size specified in a fixed-length 
string descriptor, resultant-length is set to this size. Therefore, resultant- 
length can always be used by the calling program to access a valid substring of 
radix-point-string. 

Description 

If unable to translate the logical name SYS$RADIX_POINT, LIB$RADIX_POINT 
returns the United States radix point symbol (.). If the translation succeeds, 
the text produced is returned. Thus, a system manager can define SYS$RADIX_ 
POINT as a system-wide logical name to provide a default for all users, and an 
individual user with a special need can define SYS$RADIX_POINT as a process 
logical name to override the default. 

LIB$RADIX_POINT is used implicitly by BASIC. 
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Condition Values Returned 

SS$_NORMAL 

LIB$_STRTRU 

LIB$_FATERRLIB 

LIB$_INSVIRMEM 

LIB$_INVSTRDES 


Normal successful completion. 

Successfully completed, but the radix point string 
was truncated. 

Fatal internal error. 

Insufficient virtual memory. 

Invalid string descriptor. 
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LIBSREMQHI—Remove Entry from Head of Queue 

The Remove Entry from Head of Queue routine removes an entry from the head 
of the specified self-relative interlocked queue. LIB$REMQHI makes the VAX 
REMQHI 1 instruction available as a callable routine. 

Format 

LIBSREMQHI header ,remque-address [,retry-count] 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Arguments 

header 

OpenVMS usage quadword_signed 
type quadword integer (signed) 

access modify 

mechanism by reference 

Queue header specifying the queue from which entry will be removed. The 
header argument contains the address of this signed aligned quadword integer. 
Header must be initialized to zero before first use of the queue; zero means an 
empty queue. 

remque-address 

OpenVMS usage address 
type longword (unsigned) 

access write only 

mechanism by reference 

Address of the removed entry. The remque-address argument is the address 
of an unsigned longword that contains this address. If the queue was empty, 
remque-address is set to the address of the header. 

retry-count 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

The number of times the operation is to be retried in case of secondary-interlock 
failure of the queue instruction in a processor-shared memory application. The 
retry-count argument is the address of a longword that contains the retry count 
value. A value of 1 causes no retries. The default value is 10. 


1 On AXP systems, OpenVMS AXP instructions perform the equivalent operation. 


cond_value 
longword (unsigned) 
write only 
by value 
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Description 

The queue from which LIB$REMQHI removes an entry can be in process-private, 
processor-private, or processor-shareable memory to implement per-process, 
per-processor, or across-processor queues. 

A queue is a doubly linked list. A Run-Time Library routine specifies a queue 
entry by its address. Two longwords, a forward link and a backward link, define 
the location of the entry in relation to the preceding and succeeding entries. 

A self-relative queue is a queue in which the links between entries are 
displacements; the two longwords represent the displacements of the current 
entry’s predecessor and successor. The VAX instructions INSQHI and REMQHI 
allow you to insert and remove an entry at the head of a self-relative queue. The 
corresponding Run-Time Library routines are LIB$INSQHI and LIB$REMQHI. 

The self-relative queue instructions are interlocked and cannot be interrupted, 
so that other processes cannot insert or remove queue entries while the current 
program is doing so. Since the operation requires changing two pointers at the 
same time, a high-level language cannot perform this operation without calling 
the Run-Time Library queue access routines. 

When you use these routines, cooperating processes can communicate without 
further synchronization and without danger of being interrupted, either on a 
single processor or in a multiprocessor environment. The queue Access routines 
are also useful in an AST environment; they allow you to add or remove an entry 
from a queue without being interrupted by an asynchronous system trap. 


Condition Values Returned 

SS$_NORMAL 

LIB$_ONEENTQUE 

LIB$_SECINTFAI 


LIB$_QUEWASEMP 

SS$_ROPRAND 


Routine successfully completed. The entry was 
removed from the head of the queue, and the 
resulting queue contains one or more entries. 

Routine successfully completed. The entry was 
removed from the head of the queue, and the 
resulting queue is empty. 

A secondary interlock failure occurred; the 
insertion was attempted the number of times 
specified by retry-count. This is a severe error. 
The queue is not modified. This condition can 
occur only when the queue is in memory being 
shared between two or more processors. 

The queue was empty. The queue is not modified. 
Reserved operand fault. Either the entry or the 
header is at an address that is not quadword 
aligned, or the header address equals the entry 
address. 
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LIBSREMQTI—Remove Entry from Tail of Queue 

The Remove Entry from Tail of Queue routine removes an entry from the tail 
of the specified self-relative interlocked queue. LIB$REMQTI makes the VAX 
REMQTI 1 instruction available as a callable routine. 

Format 

LIB$REMQTI header ,remque-address [,retry-count] 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Arguments 

header 

OpenVMS usage quadword_signed 
type quadword integer (signed) 

access modify 

mechanism by reference 

Queue header specifying the queue from which the entry is to be deleted. The 
header argument contains the address of this signed aligned quadword integer. 
Header must be initialized to zero before first use of the queue; zero means an 
empty queue. 

remque-address 

OpenVMS usage address 
type longword (unsigned) 

access write only 

mechanism by reference 

Address of the removed entry. The remque-address argument is the address of 
a longword that contains this address. If the queue was empty, remque-address 
is set to the address of the header. 

retry-count 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

The number of times the operation is to be retried in case of secondary-interlock 
failure of the queue instruction in a processor-shared memory application. The 
retry-count argument is the address of a longword that is this retry count value. 
A value of 1 causes no retries. The default value is 10. 


1 On AXP systems, OpenVMS AXP instructions perform the equivalent operation. 


cond_value 
longword (unsigned) 
write only 
by value 
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Description 

The queue from which LIB$REMQTI removes an in process-private, processor- 
private, or processor-shareable memory to implement per-process, per-processor, 
or across-processor queues. 

A queue is a doubly linked list. A Run-Time Library routine specifies a queue 
entry by its address. Two longwords, a forward link and a backward link, define 
the location of the entry in relation to the preceding and succeeding entries. 

A self-relative queue is a queue in which the links between entries are 
displacements; the two longwords represent the displacements of the current 
entry’s predecessor and successor. The VAX instructions INSQTI and REMQTI 
allow you to insert and remove an entry at the tail of a self-relative queue. The 
corresponding Run-Time Library routines are LIB$INSQTI and LIB$REMQTI. 

The self-relative queue instructions are interlocked and cannot be interrupted, 
so that other processes cannot insert or remove queue entries while the current 
program is doing so. Since the operation requires changing two pointers at the 
same time, a high-level language cannot perform this operation without calling 
the Run-Time Library queue access routines. 

When you use these routines, cooperating processes can communicate without 
further synchronization and without danger of being interrupted, either on a 
single processor or in a multiprocessor environment. The queue Access routines 
are also useful in an AST environment; they allow you to add or remove an entry 
from a queue without being interrupted by an asynchronous system trap. 


Condition Values Returned 

SS$_N ORMAL 

SS$_ROPRAND 


LIB$_ONEENTQUE 

LIB$_QUEWASEMP 

LIB$_SECINTFAI 


Routine successfully completed. The entry was 
removed from the queue tail, and the resulting 
queue contains one or more entries. 

Reserved operand fault. Either the entry or the 
header is at an address that is not quadword 
aligned, or the header address equals the entry 
address. 

Routine successfully completed. The entry was 
removed from the queue tail, and the resulting 
queue is empty. 

Queue was empty. The queue is not modified. 

A secondary interlock failure occurred; the 
insertion was attempted the number of times 
specified by retry-count. This is a severe error. 
The queue is not modified. This condition can 
occur only when the queue is in memory being 
shared between two or more processors. 
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LIB$RENAME_FILE—Rename One or More Files 

The Rename One or More Files routine changes the names of one or more files. 
The specification of the files to be renamed may include wildcards. 

LIB$RENAME_FILE is similar in function to the DCL command RENAME. 

Format 

LIB$RENAME_FILE old-filespec ,new-filespec [,default-filespec] [,related-filespec] [,flags] 

[,user-success-procedure] [,user-error-procedure] [,user-confirm-procedure] 

[,user-specified-argument] [,old-resultant-name] [,new-resultant-name] 

[,file-scan-context] 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Arguments 

old-filespec 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

File specification of the files to be renamed. The old-filespec argument is the 
address of a descriptor pointing to the old file specification. The specification may 
include wildcards, in which case each file which matches the specification will 
be renamed. The string must not contain more than 255 characters. Any string 
class is supported. 

new-filespec 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

File specification for the new file names. The new-filespec argument is the 
address of a descriptor pointing to the new file specification. 

This specification need not be complete; fields omitted or specified by using the 
wildcard character (*) will be filled in from the existing file’s name using the 
same rules as for the DCL command RENAME. The string must not contain more 
than 255 characters. Any string class is supported. 

default-filespec 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Default file specification of the files to be renamed. The default-filespec 
argument is the address of a descriptor pointing to the default file specification. 


cond_value 
longword (unsigned) 
write only 
by value 
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This is an optional argument; if omitted, the default is the null string. See the 
OpenVMS Record Management Services Reference Manual for information on 
default file specifications. The string must not contain more than 255 characters. 
Any string class is supported. 

related-filespec 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Related file specification of the files to be renamed. The related-filespec 
argument is the address of a descriptor pointing to the related file specification. 
This is an optional argument; if omitted, the default is the null string. Any string 
class is supported. 

Input file parsing is used. (See the OpenVMS Record Management Services 
Reference Manual for information on related file specifications and input file 
parsing.) 

The related file specification is useful when you are processing lists of file 
specifications. Unspecified portions of the file specification are inherited from the 
last file processed. Any string class is supported. This is an optional argument. 

flags 

OpenVMS usage mask_longword 
type longword (unsigned) 

access read only 

mechanism by reference 

Longword of flag bits designating optional behavior. The flags argument is the 
address of an unsigned longword containing the flag bits. This is an optional 
argument; if omitted, the default is that all flags are clear. 

The bit number, symbol, and its meaning is as follows: 

Bit Description 

0 If new-filespec does not specify a version number, this flag controls 
whether a new version number for the output file is to be assigned. If 
clear, the file is given a version number 1 higher than any previously 
existing file of the same file name and file type. This is the default action. 
If set, the current version number of the file is used. If a file already exists 
with the same file name, type and version number, the error RMS$_FEX 
is given. This flag is equivalent to the /NONEWJVERSION qualifier of the 
DCL RENAME command. 

1 Controls whether the renamed file takes on security attributes of the new 
location or keeps its existing security attributes. If set, the attributes 
of the renamed file are inherited from the next lower version of the new 
file name, if any, the new parent directory, or both. If clear, the file’s 
security attributes are not changed; this is the default action. For more 
information on file security, see the OpenVMS Security Guide . This flag is 
equivalent to the /INHERIT_SECURITY qualifier of the DCL RENAME 
command. 
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user-success-procedure 

OpenVMS usage procedure 
type procedure value 

access function call (before return) 

mechanism by value 

User-supplied success routine that LIB$RENAME_FILE calls after each 
successful rename. 

For further information on the success routine, see “Call Format for a Success 
Routine” in the Description section. 

user-error-procedure 

OpenVMS usage procedure 
type procedure value 

access function call (before return) 

mechanism by value 

User-supplied error routine that LIB$RENAME_FILE calls when it detects 
an error. The value returned by the error routine determines whether 
LIB$RENAME_FILE processes more files. For further information on the 
error routine, see “Call Format for an Error Routine” in the Description section. 

user-confirm-procedure 

OpenVMS usage procedure 
type procedure value 

access function call (before return) 

mechanism by value 

User-supplied confirm routine that LIB$RENAME_FILE calls before it renames 
a file. The value returned by the confirm routine determines whether or not 
LIB$RENAME_FILE renames the file. 

The confirm routine can be used to select specific files for renaming based on 
criteria such as expiration date, size, and so on. 

For further information on the confirm routine, see “Call Format for a Confirm 
Routine” in the Description section. 

user-specified-argument 

OpenVMS usage user_arg 
type longword (unsigned) 

access read only 

mechanism by value 

Value that LIB$RENAME_FILE passes to the success, error, and confirm routines 
each time they are called. Whatever mechanism is used to pass user-specified- 
argument to LIB$RENAME_FILE is also used to pass it to the user-supplied 
routines. This is an optional argument; if omitted, zero is passed by value. 

old-resultant-name 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor 
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String into which LIB$RENAME_FILE copies the old resultant file specification 
of the last file processed. This is an optional argument. If present, it is used 
to store the file specification passed to the user-supplied routines instead of a 
default class S, type T string. Any string class is supported. 

If you are specifying one or more of the action routine arguments, be sure that 
the descriptor class used to pass resultant-name is the same as the descriptor 
class required by the action routine. For example, VAX Ada requires a class SB 
descriptor for string arguments to Ada routines, but will use a class A descriptor 
by default when calling external routines. Refer to your language manual to 
determine the proper descriptor class to use. 

new-resultant-name 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor 

String into which LIB$RENAME_FILE writes the new RMS resultant file 
specification of the last file processed. The new-resultant-name argument is the 
address of a descriptor pointing to the new name. This is an optional argument. 
If present, it is used to store the file specification passed to the user-supplied 
routines instead of a class S, type T string. Any string class is supported. 

If you are specifying one or more of the action routine arguments, be sure that 
the descriptor class used to pass resultant-name is the same as the descriptor 
class required by the action routine. For example, VAX Ada requires a class SB 
descriptor for string arguments to Ada routines, but will use a class A descriptor 
by default when calling external routines. Refer to your language manual to 
determine the proper descriptor class to use. 

file-scan-context 

OpenVMS usage context 
type longword (unsigned) 

access modify 

mechanism by reference 

Context for renaming a list of file specifications. The file-scan-context is the 
address of a longword which contains this context. You must initialize this 
longword to zero before the first of a series of calls to LIB$RENAME_FILE. 
LIB$RENAME_FILE uses the file scan context to retain the file context for 
multiple input files. 

LIB$FILE_SCAN uses this context to retain multiple input file related file 
context. This is an optional argument; it need only be specified if you are using 
multiple input files, as the DCL command RENAME does. You may deallocate 
the context allocated by LIB$FILE_SCAN while processing the LIB$RENAME_ 
FILE requests by calling LIB$FILE_SCAN_END after all calls to LIB$RENAME_ 
FILE have been completed. See the description of LIB$FILE_SCAN for a more 
detailed description of this argument. 
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Description 

This description is divided into three parts. 

• Call Format for a Success Routine 

• Call Format for an Error Routine 

• Call Format for a Confirm Routine 

Call Format for a Success Routine 

The success routine is optional; it is called only if the user-success-procedure 
argument is specified in the call to LIB$RENAME_FILE. 

The calling format of a success routine is as follows: 

user-success-procedure old-filespec ,new-filespec [,user-specified-argument] 

old-filespec 

OpenVMS usage char_string 
type character string 

access read only 

mechanism descriptor 

RMS resultant file specification of the file before it was renamed. If old- 
resultant-name was specified, it is used to pass the string to the success routine. 
Otherwise, a class S, type T string is passed. Any string class is supported. 

new-filespec 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

RMS resultant file specification of the newly renamed file. If new-resultant- 
name was specified, it is used to pass the string to the success routine. 
Otherwise, a class S, type T string is passed. Any string class is supported. 

user-specified-argument 

OpenVMS usage user_arg 
type longword (unsigned) 

access read only 

mechanism unspecified 

Value of user-specified-argument passed by LIB$RENAME_FILE to the 
success routine using the same passing mechanism that was used to pass it 
to LIB$RENAME_FILE. 

Call Format for an Error Routine 

The error routine returns a success/fail value that LIB$RENAME_FILE uses to 
determine whether or not more files will be processed if an error is encountered. 
The error routine is called only if the user-error-procedure argument was 
specified in the call to LIB$RENAME_FILE. If the user-error-procedure 
argument was not specified, the default is to continue processing. 

The calling format of the error routine is as follows: 

user-error-procedure old-filespec ,new-filespec ,rms-sts ,rms-stv ,error-source ,user-specified-argument 
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old-filespec 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

RMS resultant file specification of the file being renamed when the error occurred. 
If old-resultant-name was specified, it is used to pass the string to the error 
routine. Otherwise, a class S, type T string is passed. Any string class is 
supported. 

new-filespec 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

RMS resultant file specification of the new file name being used when the error 
occurred. If new-resultant-name was specified, it is used to pass the string to 
the error routine. Otherwise, a class S, type T string is passed. Any string class 
is supported. 

rms-sts 

OpenVMS usage cond_value 
type longword (unsigned) 

access read only 

mechanism by reference 

Primary condition code (FAB$L_STS) which describes the error that occurred. 
The rms-sts argument is the address of an unsigned longword that contains this 
primary condition code. 

rms-stv 

OpenVMS usage cond_value 
type longword (unsigned) 

access read only 

mechanism by reference 

Secondary condition code (FAB$L_STV) which describes the error that occurred. 
The rms-stv argument is the address of an unsigned longword that contains this 
secondary condition code. 

error-source 

OpenVMS usage longword_signed 
type longword integer (signed) 

access read only 

mechanism by reference 

Integer code indicating where the error was found. The error-source argument 
is the address of a longword containing the error source. 
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The values of error-source and their meanings are as follows: 

0 Error searching for old-filespec 

1 Error parsing new-filespec 

2 Error renaming file 

user-specified-argument 

OpenVMS usage user_arg 
type longword (unsigned) 

access read only 

mechanism unspecified 

Value of user-specified-argument that LIB$RENAME_FILE passes to the 
error routine using the same passing mechanism that was used to pass it to 
LIB$RENAME_FILE. 

If the error routine returns a success status (bit 0 set), then LIB$RENAME_FILE 
will continue processing files. If the error routine returns a failure status (bit 0 
clear), processing ceases immediately and LIB$RENAME_FILE returns with an 
error status. 

If the user-error-procedure argument is not specified, LIB$RENAME_FILE 
will return to its caller the most severe error status encountered while renaming 
the files. If the error routine is called for an error, the success status LIB$_ 
ERRROUCAL is returned. 

The error routine is not called for errors related to string copying. 

Call Format for a Confirm Routine 

The calling format of a confirm routine is as follows: 

user-confirm-procedure old-filespec ,new-filespec ,old-fab [,user-specified-argument] 

old-filespec 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

RMS resultant file specification of the file about to be renamed. If old-resultant- 
name was specified, it is used to pass the string to the confirm routine. 
Otherwise, a class S, type T string is passed. Any string class is supported. 

new-filespec 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

RMS resultant file specification which the file will be given. If new-resultant- 
name was specified, it is used to pass the string to the confirm routine. 
Otherwise, a class S, type T string is passed. Any string class is supported. 
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old-fab 

OpenVMS usage fab 
type unspecified 

access read only 

mechanism by reference 

Address of the RMS FAB that describes the file being renamed. Your program 
may perform an RMS $OPEN on the FAB to obtain file attributes it needs to 
determine whether the file should be renamed, but must close the file with 
$CLOSE before returning to LIB$RENAME_FILE. 

user-specified-argument 

OpenVMS usage user_arg 
type longword (unsigned) 

access read only 

mechanism unspecified 

Value of user-specified-argument passed by LIB$RENAME_FILE to the 
confirm routine using the same passing mechanism that was used to pass it 
to LIB$RENAME_FILE. This is an optional argument. 

If the confirm routine returns a success value (bit 0 set), the file is renamed; 
otherwise, the file is not renamed. 

Condition Values Returned 


SS$_NORMAL 

LIB$_ERRROUCAL 

LIB$_INVARG 

LIB$_INVFILSPE 

LIB$_INVSTRDES 

LIB$_WRONUMARG 


Routine successfully completed. 

Success—error routine called. A file error was 
encountered but the error routine was called to 
handle the condition. 

Invalid argument. Flags has one or more 
undefined bits set. 

Invalid file specification. Old-filespec, new- 
filespec, or default-filespec contains more than 
255 characters. 

Invalid string descriptor. One of the string 
argument descriptors was not a valid string 
descriptor. 

Wrong number of arguments. An incorrect 
number of arguments was passed to 
LIB$RENAME_FILE. 


Any condition value returned by LIB$SCOPY_xxx; truncation errors are ignored. 

Any condition value returned by RMS. If the user-error-procedure argument 
was not specified, this is the most severe of the RMS errors which occurred while 
renaming the files. 
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LIB$RESERVE_EF—Reserve Event Flag 

The Reserve Event Flag routine allocates a local event flag number specified by 

event-flag-number. 


Format 

LIB$RESERVE_EF event-flag-number 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

argument 

event-flag-number 

OpenVMS usage ef_number 
type longword (unsigned) 

access read only 

mechanism by reference 

Event flag number to be allocated by LIB$RESERVE_EF. The event-flag- 
number argument contains the address of a signed longword integer that is this 
event flag number. 


Description 

LIB$RESERVE_EF allocates a particular local event flag number. It differs from 
LIB$GET_EF, which allocates an arbitrary event flag. 

Use LIB$FREE_EF to deallocate an event flag reserved with LIB$RESERVE_EF. 


Condition Values Returned 

SS$_N ORMAL 

LIB$_EF_ALRRES 

LIB$_EF_RESSYS 


Routine successfully completed. 

Event flag already reserved. 

Event flag reserved to system. This occurs if the 
event flag number is outside the ranges of 1 to 23 
and 32 to 63. 
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Example 


PROGRAM RESERVE_EF(INPUT, OUTPUT); 

routine LIB$RESERVE_EF(%REF EVENT_FLAG_NUM : INTEGER); EXTERN; 
routine LIB$FREE_EF(%REF EVENT_FLAG_NUM : INTEGER); EXTERN; 

VAR 

FLAG_NUM : INTEGER; 

BEGIN 

FLAG_NUM := 37; 

LIB$RESERVE_EF(FLAG_NUM); 

WRITELN(FLAG_NUM); 

LIB$FREE_EF(FLAG_NUM); 

END. 

The output generated by this Pascal example program is as follows: 

37 
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LIB$RESET_VM_ZONE—Reset Virtual Memory Zone 

The Reset Virtual Memory Zone routine frees all blocks of memory that were 
previously allocated from the zone. 


Format 

LIB$RESET_VM_ZONE zone-id 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Argument 


zone-id 

OpenVMS usage 

type 

access 

mechanism 


identifier 

longword (unsigned) 
read only 
by reference 


Zone identifier. The zone-id is the address of a longword that contains the 
identifier of a zone created by a previous call to LIB$CREATE_VM_ZONE or 
LIB$CREATE_USER_VM_ZONE. 


Description 

LIB$RESET_VM_ZONE frees all the blocks of memory that were previously 
allocated from the zone. The memory becomes available to satisfy further 
allocation requests for the zone; the memory is not returned to the process wide 
page pool managed by LIB$GET_VM_PAGE. Your program can continue to use 
the zone after you call LIB$RESET_VM_ZONE. 

Resetting a zone is a much more efficient way to reuse storage than individually 
freeing each allocated object in the zone. 

It is the caller’s responsibility to ensure that he or she has “exclusive” access to 
the zone while the reset operation is being performed. Results are unpredictable 
if another thread of control attempts to perform any operation on the zone while 
RESET_VM_ZONE is in progress. 

If you specified deallocation filling when you created the zone, LIB$RESET_VM_ 
ZONE will fill all of the allocated blocks that are freed. 

If the zone you are resetting was created using the LIB$CREATE_USER_VM_ 
ZONE routine, then you must have an appropriate action routine for the reset 
operation. That is, in your call to LIB$CREATE_USER_VM_ZONE, you must 
have specified a user-reset-procedure. 
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Condition Values Returned 

SS$_NORMAL 

lib$_badbloadr 


Normal successful completion. 
An invalid zone-id argument. 
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LIB$REVERT—Revert to the Handler of the Routine Activator 


AXP 


Format 


The Revert to the Handler of the Routine Activator routine deletes the condition 
handler established by LIB$ESTABLISH by clearing the address pointing to the 
condition handler from the activated routine’s stack frame. 

This routine is not available to native OpenVMS AXP programs, but is recognized 
and handled appropriately by most Digital high-level language compilers. ♦ 


LIB$REVERT 


Returns 


OpenVMS usage 

type 

access 

mechanism 


address 
address 
write only 
by value 


Previous contents of SF$A_HANDLER (longword 0) of the caller’s stack frame. 
This is the address of the condition handler previously in effect. If no condition 
handler was in effect, zero is returned. 


Arguments 

None. 


Description 

LIB$REVERT returns the address that it clears from the calling routine’s stack 
frame. LIB$REVERT is used only if your routine is to establish and then cancel 
a condition handler for a portion of its execution. 

LIB$REVERT is provided primarily for use with languages without built-in error 
handling facilities, such as FORTRAN. Do not use LIB$REVERT from BASIC, 
COBOL, Pascal, or PL/I. See the documentation for the language you are using 
for information about how that language handles errors. 

In VAX MACRO, you merely use the following instruction rather than calling 
LIB$REVERT: 

CLRL (FP) ; set handler address to 0 

; in current stack frame 

Condition Values Returned 

None. 
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LIB$RUN_PROGRAM—Run New Program 

The Run New Program routine causes the current program to stop running and 
begins execution of another program. 


Format 


LIB$RUN_PROGRAM program-name 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Argument 


program-name 

OpenVMS usage 

type 

access 

mechanism 


char_string 
character string 
read only 
by descriptor 


File name of the program to be run in place of the current program. The 
program-name argument contains the address of a descriptor pointing to this 
file name string. 


The maximum length of the file name is 255 characters. The default file type is 
.EXE. 


Description 

LIB$RUN_PROGRAM stops execution of the current program and begins 
execution of another program. 

• If successful, control does not return to the calling program. Instead, the 
$EXIT system service is called, the new program image replaces the old 
image in the user process, and the command interpreter gives control to the 
new image. 

• If unsuccessful, control returns to the command interpreter. 

This routine is supported for use with the DCL and MCR CLIs. If an image is 
run directly as a subprocess or as a detached process, there is no CLI present to 
perform this function. In those cases, the error status LIB$_NOCLI is returned. 

LIB$RUN_PROGRAM causes the current image to exit at the point of the 
call and directs the Command Language Interpreter, if one is present, to start 
running another program. If LIB$RUN_PROGRAM executes successfully, control 
passes to the second program; if not, control passes to the Command Language 
Interpreter. The calling program cannot regain control. This technique is called 
chaining. 

This routine is provided primarily for compatibility with PDP-11 systems, where 
chaining is used to extend the address space of a system. 
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This routine may also be useful in an OpenVMS environment where address 
space is severely limited and large images are not possible. For example, you 
might use chaining to perform system generation (SYSGEN) on a small virtual 
address space, for a large page file. 

With LIB$RUN_PROGRAM, the calling program can pass arguments to the 
next program in the chain only by using the common storage area. One way 
to do this is for the calling program to call LIB$PUT_COMMON to pass the 
information into the common storage area. Then the called program calls 
LIB$GET_COMMON to retrieve the data. 

In general, this practice is not recommended. There is no convenient way to 
specify the order and type of arguments passed into the common storage area; 
so programs that pass arguments in this way must know about the format of 
the data before it is passed. When you use common storage, it is very difficult to 
keep your program modular and AST-reentrant; a method of arbitration must be 
designated to define which program can modify common storage and when. 

Further, LIB$RUN_PROGRAM cannot be used if no Command Language 
Interpreter is present, as in the case of image subprocesses and detached 
subprocesses. 

If you want control to return to the caller, use LIB$SPAWN instead. 


Condition Values Returned 

LIB$_INVARG 

LIB$_NOCLI 


LIB$_UNECLIERR 


Invalid argument. 

No CLI present to perform function. The calling 
process did not have a CLI to perform the 
function or the CLI did not support the request 
type. Note that an image run as a subprocess or 
detached process does not have a CLI. 

Unexpected CLI error. The CLI returned an 
error status which was not recognized. This 
error may be caused by use of a nonstandard 
CLI. If this error occurs while using the DCL or 
MCR CLIs, please report the problem to Digital 
in a Software Performance Report (SPR). 
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LIB$SCANC—Scan for Characters and Return Relative Position 

The Scan for Characters and Return Relative Position routine is used to find 
a specified set of characters in the source string. LIB$SCANC makes the 
VAX SCANC 1 instruction available as a callable routine. 

Format 

LIB$SCANC source-string ,table-array ,byte-integer-mask 

Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Relative position in the source string of the character that terminated the 
operation, or zero if the terminator character is not found. If the source string 
has a zero length, then a zero is returned. 


Arguments 

source-string 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Source string used by LIB$SCANC to index into a table. The source-string 
argument contains the address of a descriptor pointing to this source string. 

table-array 

OpenVMS usage vector_mask_byte 

type byte (unsigned) 

access read only 

mechanism by reference, array reference 

Table that LIB$SCANC indexes into and peforms a logical AND operation with 
the byte-integer-mask byte. The table-array argument contains the address of 
an unsigned byte array that is this table. 

byte-integer-mask 

OpenVMS usage maskjbyte 
type byte (unsigned) 

access read only 

mechanism by reference 

Mask on which a logical AND operation is performed with bytes in table-array. 
The byte-integer-mask argument contains the address of an unsigned byte that 
is this mask. 


1 On AXP systems, OpenVMS AXP instructions perform the equivalent operation. 
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Description 

LIB$SCANC uses successive bytes of the string specified by source-string to 
index into a table. The byte selected from the table is the byte on which a logical 
AND operation is performed with the mask byte. The operation is terminated 
when the result of the AND operation is equal to 1. 

Condition Values Returned 

None. 
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LIB$SCOPY_DXDX—Copy Source String Passed by Descriptor to 

Destination 

The Copy Source String Passed by Descriptor to Destination routine copies a 
source string passed by descriptor to a destination string. 

Format 

LIB$SCOPY_DXDX source-string ,destination-string 

Corresponding JSB Entry Point 

LIB$SC0PY_DXDX6 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Arguments 

source-string 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Source string to be copied to the destination string by LIB$SCOPY_DXDX. The 
source-string argument contains the address of a descriptor pointing to this 
source string. The descriptor class can be unspecified, fixed-length, decimal 
string, array, noncontiguous array, varying, or dynamic. 

destination-string 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor 

Destination string to which the source string is copied. The destination-string 
argument contains the address of a descriptor pointing to this destination string. 

The following actions occur depending on the class of the destination string's 
descriptor. 


cond_value 
longword (unsigned) 
write only 
by value 
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Class Field 

Action 

DSC$K_CLASS_S,Z,SD,A,NCA 

Copy the source string. If needed, space-fill 
or truncate on the right. 

DSC$K_CLASS_D 

If the area specified by the destination 
descriptor is large enough to contain the 
source string, copy the source string and 
set the new length in the destination 
descriptor. If the area specified is not 
large enough, return the previous space 
allocation (if any) and then dynamically 
allocate the amount of space needed. Copy 
the source string and set the new length 
and address in the destination descriptor. 

DSC$K_CLASS_VS 

Copy source string to destination string up 
to the limit of DSC$W_MAXSTRLEN with 
no padding. Readjust current length field 
to actual number of bytes copied. 


Description 

LIB$SCOPY_DXDX returns all condition values as a status; truncation is a 
qualified success condition value (bit 0 set to 1). 

In addition, an equivalent JSB entry point is available, with RO containing the 
first argument and R1 containing the second. 


Condition Values Returned 

SS$_NORMAL 

LIB$_STRTRU 

LIB$_FATERRLIB 

LIB$_INSVIRMEM 

LIB$_INVSTRDES 


Routine successfully completed. All characters in 
the input string were copied to the destination 
string. 

Routine successfully completed. String 
truncated. The fixed-length destination string 
could not contain all of the characters copied 
from the source string. 

Fatal internal error. An internal consistency 
check has failed. This usually indicates an 
internal error in the Run-Time Library and 
should be reported to Digital in a Software 
Performance Report (SPR). 

Insufficient virtual memory. A call to LIB$GET_ 
VM has failed because your program has 
exceeded the image quota for virtual memory. 
Invalid string descriptor. A string descriptor has 
an invalid value in its DSC$B_CLASS field. 


LIB-352 




LIB$SCOPY_R_DX 


LIB$SCOPY_R_DX—Copy Source String Passed by Reference to 

Destination String 

The Copy Source String Passed by Reference to Destination String routine copies 
a source string passed by reference to a destination string. 


Format 

LIB$SCOPY_R_DX word-integer-source-length ,source-string .destination-string 

Corresponding JSB Entry Point 

LIB$SC0PY_R_DX6 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 


Arguments 

word-integer-source-length 

OpenVMS usage word_unsigned 
type word (unsigned) 

access read only 

mechanism by reference 

Length of the source string. The word-integer-source-length argument 
contains the address of an unsigned word that is this length. 

source-string 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by reference 

Source string to be copied to the destination string by LIB$SCOPY_R_DX. The 
source-string argument is the address of this source string. 

destination-string 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor 

Destination string to which the source string is copied. The destination-string 
argument contains the address of a descriptor pointing to this destination string. 

The following actions occur depending on the class of the destination string’s 
descriptor. 
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Class Field 

Action 

dsc$k_class_s,z,sd,a,nca 

Copy the source string. If needed, space fill 
or truncate on the right. 

DSC$K_CLASS_D 

If the area specified by the destination 
descriptor is large enough to contain the 
source string, copy the source string and 
set the new length in the destination 
descriptor. If the area specified is not 
large enough, return the previous space 
allocation (if any) and then dynamically 
allocate the amount of space needed. Copy 
the source string and set the new length 
and address in the destination descriptor. 

DSC$K_CLASS_VS 

Copy source string to destination string up 
to the limit of DSC$W_MAXSTRLEN with 
no padding. Readjust current length field 
to actual number of bytes copied. 


Description 

LIB$SCOPY_R_DX returns all condition values as a status; truncation is a 
qualified success condition value (bit 0 set to 1). 

In addition, an equivalent JSB entry is available, with RO being the first 
argument, R1 the second, and R2 the third. The length argument is passed 
in bits 15:0 of RO. 


Condition Values Returned 

SS$_N ORMAL 

LIB$_STRTRU 

LIB$_FATERRLIB 

LIB$_IN SVIRMEM 

LIB$_INVSTRDES 


Routine successfully completed. All characters in 
the input string were copied to the destination 
string. 

Routine successfully completed. String 
truncated. The fixed-length destination string 
could not contain all of the characters copied 
from the source string. 

Fatal internal error. An internal consistency 
check has failed. This usually indicates an 
internal error in the Run-Time Library and 
should be reported to Digital in a Software 
Performance Report (SPR). 

Insufficient virtual memory. A call to LIB$GET_ 
VM has failed because your program has 
exceeded the image quota for virtual memory. 

Invalid string descriptor. A string descriptor has 
an invalid value in its DSC$B_CLASS field. 
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LIB$SET_LOGICAL—Set Logical Name 

The Set Logical Name routine requests the calling process’s Command Language 
Interpreter (CLI) to define or redefine a supervisor-mode process logical name. It 
provides the same function as the DCL DEFINE command. 


Format 

LIB$SET_LOGICAL logical-name [,value-string] [.table] [.attributes] [.item-list] 

Either the item-list or value-string argument must be specified. If both item- 
list and value-string are specified, the value-string argument is ignored. 

Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Arguments 


logical-name 

OpenVMS usage 

type 

access 

mechanism 


logical_name 
character string 
read only 
by descriptor 


Logical name to be defined or redefined. The logical-name argument contains 
the address of a descriptor pointing to this logical name string. The maximum 
length of a logical name is 255 characters. Note that logical names are case- 
sensitive. 


value-string 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Value to be given to the logical name. The value-string argument contains the 
address of a descriptor pointing to this value string. The maximum length of a 
logical name value is 255 characters. 

If omitted, an item list must be present to specify the values of the logical name. 

table 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Name of the table in which to create the logical name. The table argument 
contains the address of a descriptor pointing to the logical name table. If no table 
is specified, LNM$PROCESS is used as the default. 
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attributes 

OpenVMS usage maskjongword 
type longword (unsigned) 

access read only 

mechanism by reference 

Logical name or translation attributes. The attributes argument is the address 
of a longword bit mask that contains the logical name or translation attributes. 

LNM$M_CONFINE and LNM$M_NO_ALIAS are currently available logical 
name attributes. See the description of the $CRELNM system service in 
the OpenVMS System Services Reference Manual for definitions of LNM$M_ 
CONFINE and LNM$M_NO_ALIAS. If omitted, no special logical name attribute 
is established. 

If no item-list is specified, the translation attributes LNM$M_CONCEALED 
and LNM$M_TERMINAL may be specified. See the description of the ASSIGN 
command in the OpenVMS DCL Dictionary for definitions of these attributes. 

If an item-list is specified, it will contain the translation attributes for each 
equivalence string in the attribute. 

item-list 

OpenVMS usage item_list_3 

type unspecified 

access read only 

mechanism by reference, array reference 

Item list describing the equivalence names for this logical name. The item-list 
argument contains the address of an array that contains this item list. If item- 
list is not specified, the logical name will have only one value, as specified in the 
value-string argument. Item codes for use with this item list are included in 
Digital-supplied libraries in module $LNMDEF. 

Either value-string or item-list must be specified. If neither is specified, 
the LIB$_INVARG error is produced. If both value-string and item-list are 
specified, the value-string argument is ignored. 

If item-list is specified, only logical name attributes are permitted. Translation 
attributes appear in the item list. 

Item-list is only needed when you wish to create multiple equivalence strings for 
a single logical name. 


Description 

If the optional table argument is defined, the logical name will be placed in the 
table specified by the table argument; otherwise, the logical name is placed in 
the LNM$PROCESS table. 

Unlike the system services $CRELOG and $CRELNM, LIB$SET_LOGICAL does 
not require the caller to be executing in supervisor mode to define a supervisor¬ 
mode logical name. Supervisor-mode logical names are not deleted when an 
image exits. A program can obtain the current value of any logical name by 
calling the system service $TRNLNM. For more information on logical names see 
the OpenVMS System Services Reference Manual . 
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This routine is supported for use with the DCL and MCR Command Language 
Interpreters. If an image is run directly as a subprocess or as a detached process, 
there is no CLI present to perform this function. In that case, the error status 
LIB$_NOCLI is returned. 

This routine does not support the DCL DEFINE and DEASSIGN commands’ 
special side-effect of opening and closing a process-permanent file if the logical 
name "SYS$OUTPUT M is specified. 

See the OpenVMS DCL Dictionary for a description of the DCL DEFINE 
command. 


Condition Values Returned 

SS$_NORMAL 

SS$_SUPERSEDE 

SS$_BUFFEROVF 

SS$_ACCVIO 

SS$_BADPARAM 

SS$_INSFMEM 

SS$_IVLOGNAM 

SS$_IVLOGTAB 

SS$_NOPRIV 

SS$_TOOMANYLNAM 

LIB$_INVARG 

LIB$_INVSTRDES 

LIB$_NOCLI 


LIB$_UNECLIERR 


Routine successfully completed. 

Routine successfully completed; the previous 
definition of the logical name was replaced. 

Routine successfully completed; however, a buffer 
overflow occurred. 

Access violation. The logical name or its value 
could not be read. 

Bad argument. 

Insufficient dynamic memory. 

Invalid logical name. The logical name or its 
value contained more than 255 characters. 

Invalid logical name table. 

No privileges for attempted operation. 

Logical name translation exceeded allowed depth. 

Neither the value-string nor the item-list 
argument was specified. 

Invalid string descriptor. 

No CLI present to perform function. The calling 
process did not have a CLI to perform the 
function or the CLI did not support the request 
type. Note that an image run as a subprocess or 
detached process does not have a CLI. 

Unexpected CLI error. The CLI returned an 
error status which was not recognized. This 
error may be caused by use of a nonstandard 
CLI. If this error occurs while using the DCL 
Command Language Interpreter, please report 
the problem to Digital in a Software Performance 
Report (SPR). 
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Example 


! + 

! Initialize value for logical name MY_LOG 

i _ 

SYMBOL$ = 'MY_LOG' 

SETVAL$ = 'OFF' 

CALL LIB$SET_LOGICAL (SYMBOLS, SETVAL$) 

END 

The BASIC program above sets the logical MY_LOG to OFF. This value can be 
displayed after the program is run with SHOW LOGICAL as follows: 

$ SHOW LOGICAL MY_LOG 

"MY_LOG" = "OFF" (LNM$PROCESS_TABLE) 
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LIB$SET_SYMBOL—Set Value of CLI Symbol 

The Set Value of CLI Symbol routine requests the calling process’s Command 
Language Interpreter (CLI) to define or redefine a CLI symbol. 

Format 

UB$SET_SYMBOL symbol ,value-string [,table-type-indicator] 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Arguments 

symbol 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Name of the symbol to be defined or modified by LIB$SET_SYMBOL. The 
symbol argument is the address of a descriptor pointing to this symbol string. If 
you redefine a previously defined CLI symbol, the symbol value is modified to the 
new value that you provide. 

The symbol name is converted to uppercase and trailing blanks are removed 
before use. Symbol must begin with a letter, a digit, a dollar sign ($), a hyphen 
(-), or an underscore (_). The maximum length of symbol is 255 characters. 

value-string 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Value to be given to the symbol. The value-string argument is the address of a 
descriptor pointing to this value string. 

Trailing blanks are not removed from the value string before use. The maximum 
length of value-string is 255 characters. Integer values are not allowed; 
LIB$SET_SYMBOL is intended to set string CLI symbols, not integer CLI 
symbols. 

table-type-indicator 

OpenVMS usage longword_signed 
type longword integer (signed) 

access read only 

mechanism by reference 

Indicator of the table which will contain the defined symbol. The table-type- 
indicator argument is the address of a signed longword integer that is this table 
indicator. 


cond_value 
longword (unsigned) 
write only 
by value 
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If omitted, the local symbol table is used. The following are possible values for 

table-type-indicator. 


Symbolic Name 

Value 

Table Used 

LIB$K_CLI_LOCAL_SYM 

1 

Local symbol table 

LIB$K_CLI_GLOBAL_SYM 

2 

Global symbol table 


Description 

LIB$SET_SYMBOL requests the calling process’s Command Language 
Interpreter (CLI) to define or redefine a CLI symbol. 

CLI symbols created using LIB$SET_SYMBOL may be inaccessible by other 
CLI commands. To avoid this situation, make sure that your symbol names are 
alphanumeric and that the first character is alphabetic. LIB$SET_SYMBOL is 
intended to set string CLI symbols, not integer CLI symbols. 

LIB$K_CLI_LOCAL_SYM and LIB$K_CLI_GLOBAL_SYM are defined as 
global symbols and in Digital-supplied symbol libraries (macro or module name 
$LIBCLIDEF). 

This routine is supported for use with the DCL Command Language Interpreter. 
If used with the MCR CLI, the error status LIB$_NOCLI will be returned. If an 
image is run directly as a subprocess or as a detached process, there is no CLI 
present to perform this function. In this case, the error status LIB$_NOCLI is 
returned. 


Condition Values Returned 

SS$_NORMAL 

LIB$_AMBSYMDEF 


LIB$_FATERRLIB 


LIB$_INSCLIMEM 


LIB$_IN SVIRMEM 


Routine successfully completed. 

Ambiguous symbol definition. The symbol name 
you want to define is ambiguous when compared 
with existing symbol names. This condition 
might arise if abbreviated symbols have been 
defined previously. See the OpenVMS DCL 
Dictionary for more information on abbreviated 
symbols. 

Fatal internal error. An internal consistency 
check has failed. This usually indicates an 
internal error in the Run-Time Library and 
should be reported to Digital in a Software 
Performance Report (SPR). 

Insufficient CLI memory. The CLI could not 
get enough virtual memory to assign another 
symbol. This condition may be caused by having 
too many symbols defined; deleting some symbol 
definitions may make enough room for the new 
symbol. 

Insufficient virtual memory. A call to LIB$GET_ 
VM has failed because your program has 
exceeded the image quota for virtual memory. 
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LIB$_INVARG 

LIB$_INVSTRDES 

LIB$_INVSYMNAM 

LIB$_NOCLI 

LIB$_UNECLIERR 


Invalid argument. The value of table-type- 
indicator was invalid or the length of value¬ 
string was greater than 255 characters. 

Invalid string descriptor. A string descriptor has 
an invalid value in its DSC$B_CLASS field. 

Invalid symbol name. The length of symbol was 
greater than 255 characters or symbol did not 
begin with a letter. 

No CLI present to perform function. The calling 
process did not have a CLI to perform the 
function or the CLI did not support the request 
type. Note that an image run as a subprocess or 
detached process does not have a CLI. 

Unexpected CLI error. The CLI returned an 
error status which was not recognized. This 
error may be caused by use of a nonstandard 
CLI. If this error occurs while using the DCL 
Command Language Interpreter, please report 
the problem to Digital in a Software Performance 
Report (SPR). 


Example 


! + 

! Initialize value and symbol name 

i _ 

SYMBOL$ = 'MY_SYM' 

SETVAL$ = 'ON' 

CALL LIB$SET_SYMBOL (SYMBOL$, SETVAL$) 

END 

The BASIC program above sets the symbol MY_SYM to ON. This value can be 
displayed after the program is run with SHOW SYMBOL as follows: 

$ SHOW SYMBOL MY_SYM 

"MY_SYM" = "ON" (LNM$PROCESS_TABLE) 
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LIB$SFREE1_DD—Free One Dynamic String 

The Free One Dynamic String routine returns the dynamically allocated storage 
for a dynamic string. 

Format 

LIB$SFREE1_DD descriptor-address 

Corresponding JSB entry point 

LIB$SFREE1_DD6 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Argument 

descriptor-address 

OpenVMS usage descriptor 
type quadword (unsigned) 

access modify 

mechanism by reference 

Dynamic descriptor specifying the area to be deallocated. The descriptor- 
address argument is the address of an unsigned quadword that is this descriptor. 
The descriptor is assumed to be dynamic and its class field is not checked. 

Description 

Before a routine deallocates a dynamic descriptor, it must use LIB$SFREE1_ 

DD or LIB$SFREEn_DD to deallocate the string storage space specified by 
the dynamic descriptor. Otherwise, string storage is not deallocated and your 
program can run out of memory. 

This routine deallocates the described string space and flags the descriptor as 
describing no string at all (DSC$A_POINTER = 0 and DSC$W_LENGTH = 0). 

Condition Values Returned 

SS$_NORMAL Routine successfully completed. 

LIB$_FATERRLIB Fatal internal error. 


cond_value 
longword (unsigned) 
write only 
by value 
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LIB$SFREEN_DD—Free One or More Dynamic Strings 

The Free One or More Dynamic Strings routine returns one or more dynamic 
strings to free storage. 


Format 


LIB$SFREEN_DD number-of-descriptors ,first-descriptor-array 


Corresponding JSB entry point 

LIB$SFREEN_DD6 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Arguments 

number-of-descriptors 

OpenVMS usage longword_unsigned 
type longword (unsigned) 

access read only 

mechanism by reference 

Number of adjacent descriptors to be flagged by LIB$FREEN_DD as having no 
allocated area (DSC$A_POINTER = 0 and DSC$W_LENGTH = 0). The number- 
of-descriptors argument contains the address of an unsigned longword that is 
this number. The deallocated area is returned to free storage. 

first-descriptor-array 

OpenVMS usage descriptor_array 
type quadword (unsigned) 

access modify 

mechanism by reference, array reference 

First descriptor of an array of descriptors. The first-descriptor-array argument 
contains the address of an unsigned quadword that is this first descriptor. The 
descriptors are assumed to be dynamic, and their class fields are not checked. 


Description 

Before a routine that allocates space returns to its caller, it must use 
LIB$SFREE1_DD or LIB$SFREEN_DD to deallocate the string storage 
space specified by any descriptors located in the stack. Otherwise, space is 
not deallocated and your program might run out of virtual memory. 

This routine deallocates the described string space and flags each descriptor as 
describing no string at all (DSC$A_POINTER = 0 and DSC$W_LENGTH = 0). 
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Condition Values Returned 

SS$_NORMAL Routine successfully completed. 

LIB$_FATERRLIB Fatal internal error. 
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LIB$SGET1_DD—Get One Dynamic String 

The Get One Dynamic String routine allocates dynamic virtual memory to the 
string descriptor you specify. 

Format 

LIB$SGET1_DD word-integer-length ,descriptor-part 

Corresponding JSB entry point 

LIB$SGET1_DD_R6 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Arguments 

word-integer-length 

OpenVMS usage word_unsigned 
type word (unsigned) 

access read only 

mechanism by reference 

Number of bytes of dynamic virtual memory to be allocated by LIB$SGET1_ 

DD. The word-integer-length argument is the address of an unsigned word 
that contains this number. The amount of storage allocated may be rounded 
up automatically. If the number of bytes is zero, a small amount of space is 
allocated. 

descriptor-part 

OpenVMS usage quadword_unsigned 
type quadword (unsigned) 

access write only 

mechanism by reference 

Descriptor of the dynamic string to which LIB$SGET1_DD will allocate the 
dynamic virtual memory. The descriptor-part argument contains the address of 
a descriptor that is this descriptor. 

The descriptor-part argument must contain the address of a dynamic string 
descriptor; LIB$GET1_DD returns an unpredictable result if any other type of 
descriptor is specified by this argument. 

The class field is not checked but is set to dynamic (DSC$B_CLASS = 2). The 
length field (DSC$W_LENGTH) is set to word-integer-length, and the address 
field (DSC$A_POINTER) points to the string area allocated. 


cond_value 
longword (unsigned) 
write only 
by value 
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Description 


LIB$GET1_DD is similar to LIB$SCOPY_DXDX except that no source string is 
copied. You can write anything you want in the allocated area. 

If descriptor-part already has dynamic memory allocated to it, but the amount 
allocated is less than word-integer-length, that space is deallocated before 
LIB$SGET1_DD allocates new space. 


Condition Values Returned 

SS$_N ORMAL 
LIB$_FATERRLIB 


LIB$_IN SVIRMEM 


Routine successfully completed. 

Fatal internal error. An internal consistency 
check has failed. This usually indicates an 
internal error in the Run-Time Library and 
should be reported to Digital in a Software 
Performance Report (SPR). 

Insufficient virtual memory. A call to LIB$GET_ 
VM has failed because your program has 
exceeded the image quota for virtual memory. 
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LIB$SHOW_TIMER—Show Accumulated Times and Counts 

The Show Accumulated Times and Counts routine returns times and counts 
accumulated since the last call to LIB$INIT_TIMER and displays them on 
SYS$OUTPUT. (LIB$INIT_TIMER must be called prior to invoking this routine.) 
A user-supplied action routine may change this default behavior. 


Format 

LIB$SHOW_TIMER [handle-address] [.code] [,user-action-procedure] [,user-argument-value] 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Arguments 


handle-address 

OpenVMS usage 

type 

access 

mechanism 


address 

longword (unsigned) 
read only 
by reference 


Block of storage containing the value returned by a previous call to LIB$INIT_ 
TIMER. The handle-address argument is the address of an unsigned longword 
integer containing that value. 

• If specified, the pointer must be the same value returned by a previous call to 
LIB$INIT_TIMER. 

• If omitted, LIB$SHOW_TIMER will use a block of memory allocated by 
LIB$INIT_TIMER. 

• If handle-address is omitted and LIB$INIT_TIMER has not been called 
previously, the error LIB$_INVARG is returned. LIB$INIT_TIMER must be 
called prior to a call to LIB$SHOW_TIMER. 

LIB$SHOW_TIMER assumes that LIB$INIT_TIMER has been previously called, 
and that the results of that call are stored either in a block pointed to by 
handle-address, or in the memory allocated by LIB$INIT_TIMER. 


code 

OpenVMS usage longword_signed 
type longword (signed) 

access read only 

mechanism by reference 

Integer specifying the statistic you want; if it is omitted or zero, all five statistics 
are returned on one line. The code argument is the address of a signed longword 
integer containing the statistic code. 
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The following values are allowed for the code argument. 


Value 

Description 

1 

Elapsed time 

2 

CPU time 

3 

Buffered I/O 

4 

Direct I/O 

5 

Page faults 


user-action-procedure 

OpenVMS usage procedure 
type procedure value 

access function call (before return) 

mechanism by value 

User-supplied action routine called by LIB$SHOW_TIMER. The default action of 
LIB$SHOW_TIMER is to write the results to SYS$OUTPUT. An action routine 
is useful if you want to write the results to a file, or in general, anywhere other 
than SYS$OUTPUT. 

The action routine returns either a success or failure condition value; this status 
is returned to the calling program as the value of LIB$SHOW_TIMER. 

user-argument-value 

OpenVMS usage user_arg 
type longword (unsigned) 

access read only 

mechanism by value 

A 32-bit value to be passed to the action routine without interpretation. If 
omitted, LIB$SHOW_TIMER passes a zero by value to the user routine. 


Description 

LIB$SHOW_TIMER returns the times and counts accumulated since the last 
call to LIB$INIT_TIMER. By default, when neither code nor user-action- 
procedure is specified in the call, LIB$SHOW_TIMER writes to SYS$OUTPUT 
a line giving the information listed below. 


Shown on Line 

Description 

ELAPSED = dddd hh:mm:ss.cc 

Elapsed real time 

CPU = hhhh:mm:ss.cc 

Elapsed CPU time 

BUFIO = nnnn 

Count of buffered I/O operations 

DIRIO = nnnn 

Count of direct I/O operations 

PAGEFAULTS = nnnn 

Count of page faults 


Any one or all five statistics can be written to SYS$OUTPUT or passed to your 
user-supplied action routine for other processing. 
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Call Format for an Action Routine 

Action routine is a user-supplied routine called by LIB$SHOW_TIMER. The 
action routine is used when you wish to write results to anywhere other than 
SYS$OUTPUT. The action routine is called only when you specify the user- 
action-procedure argument in the call to LIB$SHOW_TIMER. 

LIB$SHOW_TIMER calls the action routine using this format: 

user-action-procedure out-str [,user-argument-value] 

out-str 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Fixed-length string containing the statistics requested. The string is formatted 
exactly as it would be if written to SYS$OUTPUT. The leading character is blank. 

user-argument-value 

OpenVMS usage user_arg 
type longword (unsigned) 

access read only 

mechanism by value 

A 32-bit value passed to LIB$SHOW_TIMER. The user argument is passed 
without interpretation to the action routine. 

Condition Values Returned 

SS$_NORMAL Routine successfully completed. 

LIB$_INVARG Invalid argument. Either code or handle- 

address was invalid. 

Any condition values returned by LIB$PUT_OUTPUT or your action routine. 


Example 

PROGRAM SHOW_TIMER(INPUT,OUTPUT); 

{ + } 

{ This Pascal example demonstrates how to use LIB$SHOW_TIMER. 
{-} 


VAR 

RETURNED_STATUS : INTEGER; 

[EXTERNAL] FUNCTION LIB$INIT_TIMER( 

HANDLE_ADR : [REFERENCE] UNSIGNED := %IMMED 0 
) : INTEGER; EXTERNAL; 

[EXTERNAL] FUNCTION LIB$SHOW_TIMER( 

HANDLE_ADR : [REFERENCE] UNSIGNED := %IMMED 0; 

CODE : INTEGER; 

[IMMEDIATE,UNBOUND] 

ROUTINE ACTION_RTN( OUT_STR : [CLASS_S] PACKED ARRAY [L..U:INTEGER] OF CHAR; 
USER_ARG : INTEGER) ;= %IMMED 0; 

USER_ARG : INTEGER := %IMMED 0 
) : INTEGER; EXTERNAL; 


LIB-369 


LIB$SHOW_TIMER 


[EXTERNAL] FUNCTION LIB$STOP( 

CONDITION_STATUS : [IMMEDIATE,UNSAFE] UNSIGNED; 

FAO_ARGS : [IMMEDIATE,UNSAFE,LIST] UNSIGNED 

) : INTEGER; EXTERNAL; 

ROUTINE USER_ACTION_RTN( 

OUT_STR : [CLASS_S] PACKED ARRAY [L..U:INTEGER] OF CHAR; 
USER_ARG : INTEGER); 

BEGIN 

WRITELN('User argument is ',USER_ARG:1); 

WRITELN(OUT_STR); 

END; 

BEGIN 

{ + } 

{ Call LIB$INIT_TIMER to initialize RTL internal counters. 

{-} 

RETURNED_STATUS := LIB$INIT_TIMER; 

IF NOT ODD(RETURNED_STATUS) 

THEN 

LIB$STOP(RETURNED_STATUS); 

{ + } 

{ Print a line of text to waste time. 

{-} 

WRITELN('Spend time to acquire elapsed real time and page faults'); 

{+} 

{ Call LIB$SHOW_TIMER to display counters. 

{-} 

RETURNED_STATUS := LIB$SHOW_TIMER(,0,USER_ACTION_RTN,5); 

END. 


This Pascal program demonstrates how to call LIB$SHOW_TIMER. The output 
generated by this Pascal example is as follows: 

$ RUN SHOWJTIMER 

Spend time to acquire elapsed real time and page faults 
User argument is 5 

ELAPSED: 0 00:00:00.44 CPU: 0:00:00.04 
BUFIO: 1 DIRIO: 0 FAULTS: 18 
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LIB$SHOW_VM—Show Virtual Memory Statistics 


The Show Virtual Memory Statistics routine returns the statistics accumulated 
from calls to LIB$GET_VM/LIB$FREE_VM and LIB$GET_VM_PAGE 
/LIB$FREE_VMJPAGE. 


Format 

LIB$SHOW_VM [code] [,user-action-procedure] [,user-specified-argument] 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Arguments 


code 

OpenVMS usage 

type 

access 

mechanism 


longword_signed 
longword integer (signed) 
read only 
by reference 


Code specifying any one of the statistics to be written to SYS$OUTPUT or passed 
to an action routine for processing. The code argument is the address of a signed 
longword integer containing the statistic code. This is an optional argument. 

If the statistic code is omitted or is zero, statistics for values 1, 2, and 3 are 
returned on one line. 


The following values are allowed for the code argument. 


Value Statistic 

0 Statistics for values 1, 2, and 3 are returned 

1 Number of successful calls to LIB$GET_VM 

2 Number of successful calls to LIB$FREE_VM 

3 Number of bytes allocated by LIB$GET_VM but not yet deallocated by 
LIB$FREE_VM 

4 Statistics for values 5, 6, and 7 are returned 

5 Number of calls to LIB$GET_VM_PAGE 

6 Number of calls to LIB$FREE_VM_PAGE 

7 Number of VAX pages or AXP pagelets allocated by LIB$GET_VM_ 

PAGE but not yet deallocated by LIB$FREE_VM_PAGE 


user-action-procedure 

OpenVMS usage procedure 

type procedure value 

access function call (before return) 

mechanism by value 

User-supplied action routine called by LIB$SHOW_VM. By default, LIB$SHOW 
VM returns statistics to SYS$OUTPUT. An action routine is useful when 
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you want to return statistics to a file or, in general, to any place other than 
SYS$OUTPUT. The routine returns either a success or failure condition value, 
which will be returned as the value of LIB$SHOW_VM. 

For more information on the action routine, see “Call Format for an Action 
Routine” in the Description section. 

user-specified-argument 

OpenVMS usage user_arg 
type longword (unsigned) 

access read only 

mechanism by value 

A 32-bit value to be passed directly to the action routine without interpretation. 
That is, the contents of the argument list entry user-specified-argument are 
copied to the argument list entry for user-action-procedure. 


Description 

LIB$SHOW_VM returns the statistics accumulated from calls to LIB$GET_VM 
/LIB$FREE_VM and LIB$GET_VM_PAGE/LIB$FREE_VM_PAGE. By default, 
with neither code nor user-action-procedure specified in the call, LIB$SHOW_ 
VM writes a line giving the following information to SYS$OUTPUT: 

mmm calls to LIB$GET_VM, nnn calls to LIB$FREE_VM, ppp bytes still allocated 

Optionally, any one of six statistics can be output to SYS$OUTPUT and/or the 
line of information can be passed to a user-specified “action routine” for processing 
different from the default. 

Call Format for an Action Routine 

The action routine is a user-supplied routine that LIB$SHOW_VM calls if you 
specify the user-action-procedure argument in the call to LIB$SHOW_VM. 

The call format for an action routine is: 

user-action-procedure resultant-string ,user-specified-argument 

resultant-string 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor 

Statistics supplied by LIB$SHOW_VM. The resultant-string argument is 
the address of a descriptor pointing to an address into which LIB$SHOW_VM 
writes the statistics. The string is formatted exactly as it would be if written 
to SYS$OUTPUT. The first character is a blank; carriage-return/line-feed 
combinations are not included. 

user-specified-argument 

OpenVMS usage user_arg 
type longword (unsigned) 

access read only 

mechanism by value 

The 32-bit value passed to LIB$SHOW_VM is passed to the action routine 
without interpretation. If the user-specified-argument argument is omitted in 
the call to LIB$SHOW_VM, a zero is passed by value to the user routine. 
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Condition Values Returned 

SS$_NORMAL Routine successfully completed. 

LIB$_INVARG Invalid arguments. This can be caused by an 

invalid value for code. 

Any condition values returned by LIB$PUT_OUTPUT or your action routine. 
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LIB$SHOW_VM_ZONE—Return Information About a Zone 

The Return Information About a Zone routine returns formatted information 
about the specified zone, detailing such information as the zone’s name, 
characteristics, and areas, and then passes the information to the specified or 
default action routine. 

Format 

LIB$SHOW_VM_ZONE zone-id [,detail-level] [.user-action-procedure] [,user-arg] 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Arguments 

zone-id 

OpenVMS usage identifier 
type longword (unsigned) 

access read only 

mechanism by reference 

Zone identifier. The zone-id argument is the address of an unsigned longword 
containing this identifier. Use zero to indicate the default zone. 

detail-level 

OpenVMS usage longword_signed 
type longword (signed) 

access read only 

mechanism by reference 

An identifier code specifying the level of detail required by the user. The detail- 
level argument is the address of a signed longword containing this code. The 
default is minimal information. The following are valid values for detail-level: 

0 zone-id and name 

1 zone-id, name, algorithm, flags and size information 

2 zone-id, name, algorithm, flags, size information, cache information and 
area summary 

3 zone-id, name, algorithm, flags, size information, cache information, area 
summary and queue validation 

user-action-procedure 

OpenVMS usage procedure 
type procedure value 

access function call (before return) 

mechanism by value 

Optional user-supplied action routine called by LIB$SHOW_VM_ZONE. By 
default, LIB$SHOW_VM_ZONE prints statistics to SYS$OUTPUT by means 
of LIB$PUT_OUTPUT. An action routine is useful when you want to return 
statistics to a file or, in general, to any location other than SYS$OUTPUT. If 


cond_value 
longword (unsigned) 
write only 
by value 
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user-action-procedure fails, LIB$SHOW_VM_ZONE terminates and returns a 
failure code. Success codes are ignored. 

For more information on the action routine, see the Description section. 

user-arg 

OpenVMS usage user_arg 
type longword (unsigned) 

access read only 

mechanism by value 

Optional 32-bit value to be passed directly to the action routine without 
interpretation. That is, the contents of the argument list entry user-arg are 
copied to the argument list entry for user-action-procedure. 


Description 

LIB$SHOW_VM_ZONE returns formatted information about the specified zone 
and passes it to the action routine. The detail-level argument determines 
the degree of detail of the zone information returned, and this information is 
formatted into a readable display and passed to either a user action routine or to 
LIB$PUT_OUTPUT. 

The action routine is a user-supplied routine that LIB$SHOW_VM_ZONE calls if 
you specify the action-routine argument in the call to LIB$SHOW_VM_ZONE. 
If you do not specify action-routine, the information is passed to LIB$PUT_ 
OUTPUT for output to SYS$OUTPUT. The call format for an action routine is as 
follows: 

action-routine string, user-arg 


Arguments 

string 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor 

Information supplied by LIB$SHOW_VM_ZONE. The string argument is the 
address of a descriptor pointing to an address into which LIB$SHOW_VM_ZONE 
writes the requested information. The string is formatted exactly as it would be 
if written to SYS$OUTPUT. 

user-arg 

OpenVMS usage user_arg 
type longword (unsigned) 

access read only 

mechanism by value 

The 32-bit value passed to LIB$SHOW_VM_ZONE is passed to the action routine 
without interpretation. If the user-arg argument is omitted in the call to 
LIB$SHOW_VM_ZONE, a zero is passed by value to the user routine. 

If no zone-id is specified (0 is passed), the default zone is used. 
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You must ensure that you have exclusive access to the zone while information is 
being displayed. Results are unpredictable and may be inconsistent if another 
thread of control modifies the zone while this routine is displaying data or 
scanning control blocks. 

While scanning the queues and free lists, this routine may detect errors. 

If the lookaside list summary discovers a block improperly linked into the list 
so that the list appears disjointed, the count of the number of blocks of that 
particular size will be displayed as asterisks. 

Table LIB-6 lists error and warning messages which may be displayed during the 
lookaside list and area free list scans. The format is as follows: 

**** ERROR — error description **** 

**** WARNING — warning description **** 

Table LIB-6 LIB$SHOW_VM_ZONE Error and Warning Messages 
Error Message Description 

Invalid block size The size of the block is either not large enough 

to contain the necessary queue links or is 
unreasonably large. The size field has been 
corrupted, therefore the size of the block is 
reduced so the block to be dumped fits within the 
area. 

Block not owned by zone The current block is not within a section of the 

virtual address space controlled by this zone. 

It is possibly attempting to free a block not 
originally allocated from this zone. 

Block extends past the end of The end of the block is not in the area from 
area; truncated which the block has been allocated. The size field 

may have been corrupted, therefore the size of 
the block is reduced so the block to be dumped 
fits within the area. 

Block extends into The end of the block extends past the allocated 

“unallocated” block, truncated section of the area. The size field may have 

been corrupted, therefore the size of the block is 
reduced so the block to be dumped fits within the 
area. 

Current block not completely The current block extends into a nonexistent part 
accessible of the virtual address space. The size field may 

have been corrupted, therefore the size of the 
block is reduced so the block to be dumped fits 
within the area. 

Back link does not return to The back link in a doubly linked list does not 
previous block point to the previous block. 

Forward link does not point The forward link of current block points to a 
to valid address location that is not in the virtual address space. 

Free-fill mismatch One of the locations filled when the block was 

freed has been modified. 

(continued on next page) 
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Table LIB-6 (Cont.) LIB$SHOW_VM_ZONE Error and Warning Messages 


Error Message 

Description 

Boundary tag mismatch 

One of the boundary tags of the block is not 
valid. 

Warning 

Description 

Forward link of current block 
may not be valid 

The back link of the block pointed to by the 
forward link of the current block does not point 
to the current block. 

Block at nnnnnnnn is not 
accessible 

The block at location nnnnnnnn could not be 
accessed and cannot be dumped. 

Block truncated to nnnnnnnn 
bytes to prevent ACCVIO 

The block to be dumped extends into the 
unaccessible part of the address space. The 
size of the block is reduced such that the block to 
be dumped fits within the accessible addresses. 


When a block forward link is suspected of pointing to an invalid next block, 
the information from the next block is replaced by asterisks. The following is a 
sample error display. 

**** ERROR — forward link does not point to valid address **** 

Link Analysis for Current Block: 

Previous Current Next 

Block adr : 0014B270 0014C200 6B6E754A 

Forw link (abs): 0014C200 6B6E754A ******** 

Block size = 32 
Block contents: 


00000000 00000000 6B6E754A 00000020 ...Junk. 00000 0014C200 

0014B270 00000008 00000000 00000000 .p 2 .. 00010 0014C210 


Condition Values Returned 


SS$_N ORMAL 
LIB$_N OTFOU 

lib$_badzone 

LIB$_INVARG 
LIB$_INV OPEZON 

LIB$_WRONUMARG 


Normal successful completion. 

Could not find another VM zone (alternate 
success status). 

Invalid zone. Routine was called with a zone-id 
that does not represent a valid VM zone. 

Invalid argument. 

Invalid operation for zone; invalid use of 
unspecified user zone action routine. 

Wrong number of arguments. 


Any condition value returned by the user-formatted output action routine or 
LIB$PUT_OUTPUT. 
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Example 


IMPLICIT NONE 
INTEGER*4 zone_id 
INTEGER*4 LIB$SHOW_VM_ZONE 

zone_id = 0 ! request info for default zone 

call LIB$SHOW_VM_ZONE (zone_id, 1) 

END 

An example of the output generated by this FORTRAN program using detail- 
level 1 is as follows: 

ZONE_ID = 00013058, Z0NE_NAME = "DEFAULT_ZONE" 

Algorithm = LIB$K_VM_FIRST_FIT 

Flags = 00000020 

LIB $M_VM_EXTEND_AREA 

Initial size = 124 pages Current size = 0 pages 

Extend size = 128 pages Page limit = 0 pages 

Requests are rounded up to a multiple of 8 bytes, 
naturally aligned on 8-byte boundaries 

0 bytes freed and not yet reallocated 


IMPLICIT NONE 
INTEGERS zone_id 
INTEGERS LIB$SH0W_VM_Z0NE 

zone_id = 0 ! request info for default zone 

call LIB$SH0W_VM_ZONE (zone_id, 3) 

END 

An example of the output generated by this FORTRAN program using detail- 
level 3 is as follows: 

Zone Id = 00044CF8, Zone name = "Mix of lookaside list and area blocks" 

Algorithm = LIB$K_VM_QUICK_FIT with 16 Lookaside Lists ranging from 
a minimum blocksize of 8, to a maximum blocksize of 128 

Flags = 00000028 

LIB $M_VM_FREE_FILL 0 
LIB $M_VM_EXTEND_AREA 

Initial size = 16 pages Current size = 256 pages in 1 area 

Extend size = 16 pages Page limit = None 

Requests are rounded up to a multiple of 8 bytes, 
naturally aligned on 8-byte boundaries ' 

129896 bytes have been freed and not yet reallocated 

312 bytes are used for zone and area control blocks, or 0.2% overhead 

Quick Fit Lookaside List Summary: 
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List 

number 

Block 

size 

Number of 
blocks 

2 

16 

7 

3 

24 

9 

4 

32 

8 

5 

40 

6 

6 

48 

12 

7 

56 

6 

8 

64 

7 

9 

72 

7 

10 

80 

5 

11 

88 

4 

12 

96 

8 

13 

104 

3 

14 

112 

5 

15 

120 

12 

16 

128 

6 

Area Summary: 




First 

Last 

Pages 

Bytes not yet 

address 

address 

assigned 

allocated 

00065400 

000853FF 

256 

1176 


Scanning Lookaside Lists in Zone Control Block 
Scanning Free List for Area at 00065400 

Number of blocks = 84, Min blocksize = 160, Max blocksize = 5768 
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LIBSSIGNAL—Signal Exception Condition 

The Signal Exception Condition routine generates a signal that indicates that an 
exception condition has occurred in your program. If a condition handler does not 
take corrective action and the condition is severe, then your program will exit. 

Format 

LIBSSIGNAL condition-value [,number-of-arguments] [,FAO-argument...] 

Returns 

None. 

Arguments 

condition-value 

OpenVMS usage 
type 
access 
mechanism 

OpenVMS 32-bit condition value. The condition-value argument is an unsigned 
longword that contains this condition value. 

The OpenVMS Programming Concepts Manual explains the format of an 
OpenVMS condition value. 

n u m ber-of-a rg u men ts 

OpenVMS usage longword_signed 
type longword integer (signed) 

access read only 

mechanism by value 

Number of FAO arguments associated with condition-value. The optional 
number-of-arguments argument is a signed longword integer that contains this 
number. If omitted or specified as zero, no FAO arguments follow. 

FAO-argument 

OpenVMS usage varying_arg 
type unspecified 

access read only 

mechanism by value 

Optional FAO (formatted ASCII output) argument that is associated with the 
specified condition value. 

The OpenVMS Programming Concepts Manual explains the message format. 

condition-value2 

OpenVMS usage cond_value 
type longword (unsigned) 

access read only 

mechanism by value 

OpenVMS 32-bit condition value. The optional condition-value2 argument is an 
unsigned longword that contains this condition value. 


cond_value 
longword (unsigned) 
read only 
by value 
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The OpenVMS Programming Concepts Manual explains the format of an 
OpenVMS condition value. 

number-of-arguments2 

OpenVMS usage longword_signed 
type longword integer (signed) 

access read only 

mechanism by value 

Number of FAO arguments associated with the condition value. The optional 
number-of-arguments2 argument is a signed longword integer that contains 
this number. If omitted or specified as zero, no FAO arguments follow. 

FAO-argument2 

OpenVMS usage varying_arg 
type unspecified 

access read only 

mechanism by value 

Optional FAO (formatted ASCII output) argument that is associated with the 
specified condition value. 

The OpenVMS Programming Concepts Manual explains the message format. 


Description 

Your program calls LIB$SIGNAL whenever it needs to indicate an exception 
condition or output a message rather than return a status code to its calling 
program. 

LIB$SIGNAL examines the primary and secondary exception vectors and then 
scans the stack, frame by frame, starting at the top of the stack, and calls each 
condition handler it finds. LIB$SIGNAL locates stack frames by using each 
frame’s saved frame pointer (FP) to chain back through the stack frames. The 
OpenVMS Programming Concepts Manual provides additional information on this 
process. 

If one of the handlers that LIB$SIGNAL calls returns a continue code (that is, 
any success completion code with bit 0 set to 1), LIB$SIGNAL returns to its 
caller, which should be prepared to continue execution. 

If the handler that LIB$SIGNAL calls returns a resignal code (that is, any 
completion code with bit 0 set to 0) LIB$SIGNAL continues to scan the stack. 

If the handler called by LIB$SIGNAL calls SYS$UNWIND, control will not 
return to LIB$SIGNAL’s caller, thus changing the program flow. A handler can 
also modify the saved copy of R0/R1 in the mechanism vector, changing registers 
R0 and R1 after the stack has been unwound. If a handler does neither of these 
things, then all registers including R0/R1 and the hardware condition codes 1 are 
preserved. 

LIB$SIGNAL will, if necessary, scan up to 65,536 previous stack frames and then 
finally examine the last-chance exception vector. 

The LIB$SIGNAL argument list, the Program Counter (PC) and Processor Status 
Longword (PSL on VAX systems, PS on AXP systems) of the caller are appended 
to build the signal argument vector. 


1 Not available on OpenVMS AXP systems. 
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Condition Values Returned 

None. 


Examples 

i. c+ 

C This FORTRAN example program demonstrates the use of 
C LIB$SIGNAL. 

C 

C This program defines SS$... signals and then calls LIB$SIGNAL 
C passing the access violation code as the argument. 

C- 


INCLUDE '($SSDEF)' 

CALL LIB$SIGNAL ( %VAL(SS$_ACCVIO) ) 
END 


In FORTRAN, this code fragment signals the standard system message 
ACCESS VIOLATION. 


The output generated by this FORTRAN program on an OpenVMS AXP 
system is as follows: 


%SYSTEM-F-ACCVIO, access violation, reason mask=10, virtual address=03C00020, 
PC=00000000, PS=08000000 
%TRACE-F-TRACEBACK, symbolic stack dump follows 


module name 
D2$MAIN 


routine name 
D2$MAIN 


line 

683 


rel PC abs PC 
00000010 00000410 


2 . 


This VAX MACRO example program demonstrates the use of LIB$SIGNAL 
by forcing an access violation to be signaled. 

.EXTRN SS$_ACCVIO ; Declare external symbol 
.ENTRY START,0 

PUSHL #SS$_ACCVIO ; Condition value symbol 
; for access violation 

CALLS #1, G A LIB$SIGNAL ; Signal the condition 
RET 

.END START 


.EXTRN SS$_ACCVIO 

PUSHL #SS$_ACCVIO 

CALLS #1, LIB$SIGNAL 


Declare external symbol 
Condition value symbol 
for access violation 
Signal the condition 


This example shows the equivalent VAX MACRO code. The output generated 
by this program on a OpenVMS VAX system is as follows: 

%SYSTEM-F-ACCVIO, access violation, reason mask=0F, virtual address=03C00000, 
PC=00000000, PSL=00000000 
%TRACE-F-TRACEBACK, symbolic stack dump follows 

module name routine name line rel PC abs PC 

.MAIN. START 0000000F 0000020F 
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3. #include <ssdef.h> 

tinclude <lib$routines.h> 

main() 

{ 

/* 

** lib$signal will append the PC/PS to argument list, 

** so pass only first two FAO arguments to lib$signal 
*/ 

lib$signal(SS$_ACCVIO, 4, -559038737); /* Shouldn't return */ 

return (SS$_NORMAL); /* Exit if it does */ 

} 

This example shows the equivalent C code. The output generated by this 
program on an OpenVMS AXP system is as follows: 


%SYSTEM-F-ACCVIO, access violation, reason mask=04, virtual address=DEADBEEF, 
PC=00020034, PS=0000001B 
%TRACE-F-TRACEBACK, symbolic stack dump follows 
Image Name Module Name Routine Name Line Number rel PC abs PC 

LIB$SIGNAL 0 00010034 00020034 

LIB$SIGNAL 0 000100A0 000200A0 

0 82F01158 82F01158 
0 7FF190D0 7FF190D0 
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LIB$SIG_TO_RET—Signal Converted to a Return Status 

The Signal Converted to a Return Status routine converts any signaled condition 
value to a value returned as a function. The signaled condition is returned to the 
caller of the user routine that established the handler that is calling LIB$SIG_ 
TO_RET. This routine may be established as or called from a condition handler. 


Format 

LIB$SIG_TO_RET signal-arguments .mechanism-arguments 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Arguments 


signal-arguments 

OpenVMS usage 

type 

access 

mechanism 


vector_longword_unsigned 

unspecified 

read only 

by reference, array reference 


Signal argument vector. The signal-arguments argument contains the address 
of an array that is this signal argument vector stack. 

See the OpenVMS Programming Concepts Manual for a description of the signal 
argument vector. 


mechanism-arguments 

OpenVMS usage structure 
type unspecified 

access read only 

mechanism by reference 

Mechanism arguments vector. The mechanism-arguments argument contains 
the address of a structure that is this mechanism argument vector stack. 

See the OpenVMS Programming Concepts Manual for a description of the 
mechanism argument vector. 


Description 

LIB$SIG_TO_RET is called with the argument list that was passed to a condition 
handler by the OpenVMS Condition Handling Facility. The signaled condition 
is converted to a value returned to the routine that called the routine that 
established the handler. That action is performed by unwinding the stack to the 
caller of the establisher of the condition handler. The condition code is returned 
as the value in RO. See the OpenVMS Programming Concepts Manual for more 
information on condition handling. 

LIB$SIG_TO_RET causes the stack to be unwound to the caller of the routine 
that established the handler which was called by the signal. 
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Condition Values Returned 

SS$_NORMAL Routine successfully completed; SS$_UNWIND 

completed. Otherwise, the error code from SS$_ 
UNWIND is returned. 


Example 


c+ 

C This FORTRAN example demonstrates how to use LIB$SIG_TO_RET. 

C 

C This function subroutine inverts each entry in an array. That is, 

C a(i,j) becomes l/a(i,j). The subroutine has been declared as an integer 
C function so that the status of the inversion may be returned. The status 
C should be success, unless one of the a(i,j) entries is zero. If one of 
C the a(i,j) = 0, then l/a(i,j) is division by zero. This division by zero 
C does not cause a division by zero error, rather, the routine will return 
C signal a failure. 

C- 

INTEGER*4 FUNCTION FLIP(A,N) 

DIMENSION A(N,N) 

EXTERNAL LIB$SIG_TO_RET 

CALL LIB$ESTABLISH (LIB$SIG_TO_RET) 

FLIP = .TRUE. 

C+ 

C Flip each entry. 

C- 

DO 1 I = 1, N 
DO 1 J = 1, N 

1 A(I,J) = 1.0/A(I,J) 

RETURN 

END 

C+ 

C This is the main code. 

C- 

INTEGER STATUS, FLIP 

REAL ARRAY_1(2,2),ARRAY_2(3,3) 

DATA ARRAY_1/1,2,3,4/,ARRAY_2/l,2,3,5,0,5,6,7,2/ 

CHARACTER*32 TEXT(2),STRING 

DATA TEXT(1) /' This array could be flipped. '/, 

1 TEXT(2)/' This array could not be flipped.'/ 

STRING = TEXT(1) 

STATUS = FLIP(ARRAY_1,2) 

IF ( .NOT. STATUS) STRING = TEXT(2) 

TYPE '(a)', STRING 

STRING = TEXT(l) 

STATUS = FLIP(ARRAY_2,3) 

IF ( .NOT. STATUS) STRING = TEXT(2) 

TYPE '(a)', STRING 

END 


This FORTRAN example program inverts each entry in an array. The output 
generated by this program is as follows: 

This array could be flipped. 

This array could not be flipped. 
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LIB$SIG_TO_STOP—Convert a Signaled Condition to a Signaled 

Stop 

The Convert a Signaled Condition to a Signaled Stop routine converts a signaled 
condition to a signaled condition that cannot be continued. 

Format 

LIB$SIG_TO_STOP signal-arguments .mechanism-arguments 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Arguments 

signal-arguments 

OpenVMS usage vector_longword_unsigned 
type unspecified 

access modify 

mechanism by reference, array reference 

Signal argument vector. The signal-arguments argument contains the address 
of an array that is this signal argument vector stack. 

See the OpenVMS Programming Concepts Manual for a description of the signal 
argument vector. 

mechanism-arguments 

OpenVMS usage structure 
type unspecified 

access read only 

mechanism by reference 

Mechanism argument vector. The mechanism-arguments argument contains 
the address of a structure that is this mechanism argument vector stack. 

See the OpenVMS Programming Concepts Manual for a description of the 
mechanism argument vector. 

Description 

LIB$SIG_TO_STOP causes a signal to appear as though it had been signaled 
by a call to LIB$STOP. When a signal is generated by LIB$STOP, the severity 
code is forced to SEVERE and control cannot return to the routine that signaled 
the condition. LIB$SIG_TO_STOP may be enabled as a condition handler for a 
routine or it may be called from a condition handler. 

If the condition value in signal-arguments is SS$_UNWIND, then LIB$SIG_ 
TO_STOP returns the error condition LIB$_INVARG. 


cond_value 
longword (unsigned) 
write only 
by value 
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Condition Values Returned 

SS$_N ORMAL 

LIB$_INVARG 


Routine successfully completed; SS$_UNWIND 
completed. Otherwise, the error code from SS$_ 
UNWIND is returned. 

Invalid argument. The condition code in signal- 
arguments is SS$_UNWIND. 
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LIB$SIM_TRAP—Simulate Floating Trap 


AXP 


The Simulate Floating Trap routine converts floating faults to floating traps. It 
can be enabled as a condition handler or can be called by one. 

This routine is not available to native OpenVMS AXP programs, but is available 
to translated VAX images. ♦ 


Format 

LIB$SIM_TRAP signal-arguments ,mechanism-arguments 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Arguments 


signal-arguments 

OpenVMS usage 

type 

access 

mechanism 


vector_longword_unsigned 

unspecified 

modify 

by reference, array reference 


Signal argument vector. The signal-arguments argument contains the address 
of an array that is this signal argument vector stack. 


See the OpenVMS Programming Concepts Manual for a description of the signal 
argument vector. 


mechanism-arguments 

OpenVMS usage vector_longword_unsigned 
type unspecified 

access read only 

mechanism by reference, array reference 

Mechanism argument vector. The mechanism-arguments argument contains 
the address of an array that is this mechanism argument vector stack. 

See the OpenVMS Programming Concepts Manual for a description of the 
mechanism argument vector. 


Description 

LIB$SIM_TRAP converts floating faults to floating traps. It can be enabled as a 
condition handler or can be called by one. 

LIB$SIM_TRAP intercepts floating overflow, underflow, and divide-by-zero faults. 
It simulates the instruction causing the condition up to the point where a fault 
should be signaled, then signals the corresponding floating trap. 

Since LIB$SIM_TRAP nullifies the condition handling for the original fault 
condition, the final condition signaled by the routine will be from the context of 
the instruction itself, rather than from the condition handler. The signaling path 
is identical to that of a hardware-generated trap. The signal argument vector 
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is placed so the last entry in the vector will be the user’s stack pointer at the 
completion of the instruction (for a trap), or at the beginning of the instruction 
(for a fault). 

See the VAX Architecture Reference Manual for more information on faults and 
traps. 

Condition Values Returned 

SS$_RESIGNAL Resignal condition to next handler. The exception 

was not one that LIB$SIM_TRAP could handle. 
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LIBSSKPC—Skip Equal Characters 

The Skip Equal Characters routine compares each character of a given string 
with a given character and returns the relative position of the first nonequal 
character as an index. LIB$SKPC makes the VAX SKPC 1 instruction available 
as a callable routine. 


Format 

LIB$SKPC character-string .source-string 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

The relative position in the source string of the first unequal character. 
LIB$SKPC returns a zero if the source string was of zero length or if every 
character in source-string was equal to character-string. 


Arguments 

character-string 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

String whose initial character is to be used by LIB$SKPC in the comparison. The 
character-string argument contains the address of a descriptor pointing to this 
string. Only the first character of character-string is used, and the length of 
character-string is not checked. 

source-string 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

String to be searched by LIB$SKPC. The source-string argument contains the 
address of a descriptor pointing to this string. 


Description 

LIB$SKPC compares the initial character of character-string with successive 
characters of source-string until it finds an inequality or reaches the end of the 
source-string. It returns the relative position of this unequal character as an 
index, which is the relative position of the first occurrence of a substring in the 
source string. 


1 On AXP systems, OpenVMS AXP instructions perform the equivalent operation. 
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Condition Values Returned 

None. 

Example 


c+ 

C This FORTRAN example program shows the use of LIB$SKPC. 

C LIB$SKPC compares each character of a given string with a given character. 

C It returns the relative position of the first nonequal character as an index. 

C- 

I = LIB$SKPC (' ', ' ABC') 

TYPE 1, I 

1 FORMAT(' The blank character matches the',l2,'nd character in') 

TYPE *,'the string " ABC"' 

J = LIB$SKPC ('A', 'AAA' ) 

TYPE 2, J 

2 FORMAT(' The character "A" matches the',I2,'th character in') 

TYPE *,'the string " AAA "' 

END 

This FORTRAN example generates the following output: 

The blank character matches the 2nd character in 
the string " ABC" 

The character "A" matches the Oth character in 
the string " AAA" 
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LIBSSPANC—Skip Selected Characters 


The Skip Selected Characters routine is used to skip a specified set of characters 
in the source string. LIB$SPANC makes the VAX SPANC 1 instruction available 
as a callable routine. 


Format 


LIBSSPANC source-string .table-array ,byte-integer-mask 


Returns 


OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

The relative position in the source string of the character that terminated the 
operation is returned if such a character is found. Otherwise, zero is returned. If 
the source string has a zero length, then a zero is returned. 


Arguments 

source-string 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Source string used by LIB$SPANC to index into table-array. The source-string 
argument contains the address of a descriptor pointing to this source string. 

table-array 

OpenVMS usage vector_mask_byte 

type byte (unsigned) 

access read only 

mechanism by reference, array reference 

Table that LIB$SPANC indexes into and performs an AND operation with the 
byte-integer-mask byte. The table-array argument contains the address of an 
unsigned byte array that is this table. 

byte-integer-mask 

OpenVMS usage maskjbyte 
type byte (unsigned) 

access read only 

mechanism by reference 

Mask that an AND operation is performed with bytes in table-array. The byte- 
integer-mask argument contains the address of an unsigned byte that is this 
mask. 


1 On AXP systems, OpenVMS AXP instructions perform the equivalent operation. 
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Description 

LIB$SPANC uses successive bytes of the string specified by source-string to 
index into a table. An AND operation is performed on the byte selected from the 
table and the mask byte. 

The operation is terminated when the result of the AND operation is zero. 

Condition Values Returned 

None. 


Example 


This FORTRAN program demonstrates how to use 
LIB$SCANC and STR$UPCASE. 

Declare the Run-Time Library routines to be used. 

INTEGER*4 STR$UPCASE ! Translate to upper case 

INTEGER*4 LIB$SCANC ! Look for characters 

INTEGER*4 LIB$SPANC ! Skip over characters 


! + 

! Declare the alphabet from which "words" are constructed. 


CHARACTER*(38) ALPHABET 

DATA ALPHABET /'ABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789$ '/ 


I + 

! Local variable declarations 

i _ 


INTEGER*4 WORD_COUNT /0/ 
INTEGER*4 WORD_LENGTH /0/ 
INTEGER*4 TOTAL_LENGTH /0/ 
INTEGER*4 START_POS /0/ 

INTEGER*4 END_POS /0/ 

REAL * 4 AVERAGE_LENGTH /0.0/ 

CHARACTER*80 LINE 

BYTE MATCH_TABLE(0:255) 7256*0/ 


i Count of words found 
! Length of a word 
! Sum of word lengths 
! Position of start of word 
! Position of end of word 
! Average length of words 
! Line to examine for words 
! Match table for scanning 


! + 

I The routines LIB$SCANC and LIB$SPANC require a table with an entry 
! for each possible character. Create a match table from ALPHABET 
! with an entry of 1 if the character is in ALPHABET, 0 otherwise. 

! MATCH_TABLE has already been initialized to zeros. 


DO I = 1, LEN(ALPHABET) 

MATCH_TABLE(ICHAR(ALPHABET(1:1))) = 1 
END DO 


! + 

! Loop forever finding words in LINE. When LINE is exhausted, 
! indicated by a START_POS of zero, read another one. Upon 
! end-of-file, leave the loop and print the statistics. 
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OPEN( UNIT = 1, FILE = 'TEST.DAT', TYPE = 'OLD' ) 

DO WHILE (.TRUE.) 

DO WHILE (START_POS .EQ. 0) ! Get a new line 

READ (1,'(A)',END=900) LINE ! If EOF, skip to 900 
CALL STR$UPCASE (LINE,LINE) ! Convert to upper 

! case for matching 

START_POS = LIB$SCANC (LINE,MATCH_TABLE,1) ! Find beginning 
END DO ! of first word 


! + 

! START_POS now points to the beginning of a word. Call LIB$SPANC to 
! find the first character that is not part of the word. Set 
! START_POS to beginning of next word. If LIB$SPANC does not 
! find a non-word character, it returns zero. 

i _ 

END_POS = 

1 START_POS + LIB$SPANC (LINE(START_POS:), MATCH_TABLE,1) - 1 

IF (END_POS .LT. START_POS) THEN ! Word goes to end of line 
WORD_LENGTH = (LEN(LINE) + 1) - START_POS 
START_POS = 0 i Indicate line exhausted 

ELSE 

WORD_LENGTH = END_POS - START_POS 
STARTUPOS = 

1 END_POS + LIB$SCANC (LINE(END_POS:),MATCHJTABLE,1) - 1 

IF (START_POS .LT. END_POS) START_POS = 0 ! No more words on line 
END IF 

! + 

! Update count and length statistics. 

i _ 

WORD_COUNT = WORD_COUNT + 1 
TOTAL_LENGTH = TOTAL_LENGTH + WORD_LENGTH 
END DO 

900 CONTINUE 
! + 

! Compute average word length and display statistics. 

i _ 

IF (WORD_COUNT .NE. 0) 

1 AVERAGE_LENGTH = FLOAT(TOTAL_LENGTH) / FLOAT(WORD_COUNT) 

TYPE 901,WORD_COUNT,AVERAGE_LENGTH 

901 FORMAT (IX,110,' words found, average length was ', 

1 F4.1,' letters.') 

CLOSE (1) 

END 

This FORTRAN program reads text from the default input unit and looks for 
words. A word is defined as a string containing only the characters A to Z 
(uppercase or lowercase), 0 to 9, and the dollar sign ($), and underscore (_) 
symbols. The program reports the total number of words found and their average 
length. 

The program uses three Run-Time Library routines: STR$UPCASE, 
LIB$SCANC, and LIB$SPANC. 

1. The string is converted to uppercase using STR$UPCASE so that the search 
for words will ignore the case of letters. 

2. LIB$SCANC searches through the string for one of a set of characters, the set 
being specified as nonzero elements in a 256-byte table. 
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3. Similarly, LIB$SPANC uses the VAX SPANC 1 instruction to search through 
a string for a character whose table entry is not zero. 

The value returned by each routine is the index into the string where the first 
matching (or nonmatching) character was found, or zero if no match was found. 

The output generated by this FORTRAN program is as follows: 

12 words found, average length was 4.2 letters. 


1 On AXP systems, OpenVMS AXP instructions perform the equivalent operation. 
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LIB$SPAWN—Spawn Subprocess 

The Spawn Subprocess routine requests the command language interpreter 
(CLI) of the calling process to spawn a subprocess for executing CLI commands. 
LIB$SPAWN provides the same function as the DCL SPAWN command. 

Format 

LIB$SPAWN [command-string] [,input-file] [,output-file] [,flags] [,process-name] [,process-id] 

[,completion-status-address] [,byte-integer-event-flag-num] [,AST-address] 
[,varying-AST-argument] [prompt-string] [,cli] [.table] 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Arguments 

command-string 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

CLI command to be executed by the spawned subprocess. The command-string 
argument is the address of a descriptor pointing to this CLI command string. If 
omitted, commands are taken from the file specified by input-file. 

input-file 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Equivalence name to be associated with the logical name SYS$INPUT in the 
logical name table for the subprocess. The input-file argument is the address 
of a descriptor pointing to this equivalence string. If omitted, the default is the 
caller’s SYS$INPUT. 

output-file 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Equivalence name to be associated with the logical names SYS$OUTPUT and 
SYS$ERROR in the logical name table for the subprocess. The output-file 
argument is the address of a descriptor pointing to this equivalence string. If 
omitted, the default is the caller’s SYS$OUTPUT. 


cond_value 
longword (unsigned) 
write only 
by value 
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flags 

OpenVMS usage 

type 

access 

mechanism 


mask_longword 
longword (unsigned) 
read only 
by reference 


Flag bits that designate optional behavior. The flags argument is the address of 
an unsigned longword that contains these flag bits. By default, all flags are clear. 


These flags are defined as follows: 


Bit Symbol 


Meaning 


0 NOWAIT 

1 NOCLISYM 

2 NOLOGNAM 

3 NOKEYPAD 

4 NOTIFY 

5 NOCONTROL 

6 TRUSTED 

7 AUTHPRIV 

8 SUBSYSTEM 


If set, the calling process continues executing in parallel with 
the subprocess. If clear, the calling process hibernates until the 
subprocess completes. 

If set, the spawned subprocess does not inherit CLI symbols from 
its caller. If clear, the subprocess inherits all currently defined CLI 
symbols. You may want to specify NOCLISYM to help prevent 
commands redefined by symbol assignments from affecting the 
spawned commands. 

If set, the spawned subprocess does not inherit process logical names 
from its caller. If clear, the subprocess inherits all currently defined 
process logical names. You may want to specify NOLOGNAM to 
help prevent commands redefined by logical name assignments from 
affecting the spawned commands. 

If set, the keypad symbols and state are not passed to the subprocess. 
If not set, the keypad settings are passed to the subprocess. 

If set, a message is broadcast to SYS$OUTPUT when the subprocess 
completes or aborts. If not set, no message is broadcast. This bit 
should not be set unless the NO WAIT bit is also set. 

If set, no carriage-return/line-feed is prefixed to any prompt string. 

If not set, a carriage-return/line-feed is prefixed to any prompt string 
specified. 

If set, indicates spawn command on behalf of application. If not set, 
indicates spawn command originates from user. Spawn commands 
originating from users are disallowed in captive accounts (DCL). 1 

If set, subprocess inherits the caller’s authorized privileges. If clear, 
spawned processes’ authorized mask is set equal to the caller’s 
current (active) privilege mask. 1 

If set, spawned process inherits protected subsystem IDs for the 
duration of LOGINOUT.EXE (used to map the CLI). The IDs will 
be removed in the process of transferring control to the CLI (as a 
user mode $RUNDWN is performed). If clear, LOGINOUT does not 
execute under the subsystem IDs. 1 


1 Available only on OpenVMS VAX systems. 


AXP 


On OpenVMS AXP systems, bits 6 through 8 are reserved for future expansion 
and must be zero. ♦ 
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Bits 9 through 31 are reserved for future expansion and must be zero. Symbolic 
flag names are defined in Digital supplied libraries, in module $CLIDEF. They 
are CLI$M_NOWAIT, CLI$M_NOCLISYM, CLI$M_NOLOGNAM, CLI$M_ 
NOKEYPAD, CLI$M_NOTIFY, and CLI$M_NOCONTROL. 

Additional OpenVMS VAX symbolic flag names defined in Digital-supplied 
libraries, in module $CLIDEF, include: CLI$M_TRUSTED, CLI$M_AUTHPRIV, 
and CLI$M_SUBSYSTEM. ♦ 

process-name 

OpenVMS usage process_name 
type character string 

access read only 

mechanism by descriptor 

Name defined for the subprocess. The process-name argument is the address of 
a descriptor pointing to this name string. If omitted, a unique process name will 
be generated. If you supply a name and it is not unique, LIB$SPAWN will return 
the condition value SS$_DUPLNAM. 

process-id 

OpenVMS usage processed 
type longword (unsigned) 

access write only 

mechanism by reference 

Process identification of the spawned subprocess. The process-id argument is 
the address of an unsigned longword that contains this process identification 
value. 

This process identification value is meaningful only if the NO WAIT flags bit is 
set. 

completion-status-address 

OpenVMS usage address 
type address 

access read only 

mechanism by value 

The final completion status of the subprocess. The completion-status-address 
argument contains the address of the status. LIB$SPAWN writes the value of the 
final completion status of the subprocess into completion-status-address. Note 
that completion-status-address is updated asynchronously. Your program must 
ensure that the address is still valid when the address is written. 

If the NO WAIT flags bit is set, this value is not stored until the subprocess 
completes; use the byte-integer-event-flag-num or AST-address arguments to 
determine when the subprocess has completed. 

byte-integer-event-flag-num 

OpenVMS usage byte_unsigned 
type byte (unsigned) 

access read only 

mechanism by reference 

The number of a local event flag to be set when the spawned subprocess 
completes. The byte-integer-event-flag-num argument is the address of an 
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unsigned byte that contains this event flag number. If omitted, no event flag is 
set. 

Specifying byte-integer-event-flag-num is meaningful only if the NO WAIT 
flags bit is set. 

AST-address 

OpenVMS usage procedure 

type procedure value 

access call without stack unwinding 

mechanism by value 

Routine to be called by means of an AST when the subprocess completes. 
Specifying AST-address is meaningful only if the NOWAIT flags bit is set. 

varying-AST-argument 

OpenVMS usage user_arg 
type longword (unsigned) 

access read only 

mechanism by value 

A value to be passed to the AST routine. Typically, the varying-AST-argument 
argument is the address of a block of storage the AST routine will use. 

Specifying varying-AST-argument is meaningful only if the NO WAIT flags bit 
is set and if AST-address has been specified. 

prompt-string 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

Prompt string to use in the subprocess. The prompt-string argument is the 
address of a descriptor pointing to this prompt string. If omitted, the subprocess 
will use the same prompt string that the parent process uses. 

cli 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

File specification for the command language interpreter (CLI) to be run in the 
subprocess. The cli argument is the address of this file specification string’s 
descriptor. The CLI specified must reside in SYS$SYSTEM with a file type of 
EXE, and it must be installed. No directory or file type may be specified. The cli 
argument must be specified in all uppercase characters. 

If omitted, the subprocess will use the same CLI as the parent process. If 
specified, no context will be copied to the subprocess. 

table 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 
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File specification for the command tables to be used by the spawned process. The 
table argument is the address of this file specification string’s descriptor. The 
table specified must reside in SYS$SHARE with a file type of EXE, and it must 
be installed. 

If omitted, the subprocess will use the same table as the parent process. 


Description 

The subprocess created by LIB$SPAWN inherits the following attributes from the 
caller’s environment: 

• Process logical names 

• Global and local CLI symbols 

• Default device and directory 

• Process privileges 

• Process nondeductible quotas 

• Current command verification setting 

The subprocess does not inherit process-permanent files, nor routine or image 
context. 

Though the subprocess inherits the caller’s process privileges as its own process 
privileges, the set of authorized privileges in the subprocess is inherited from 
the caller’s current privileges. If the calling image is installed with elevated 
privileges, these privileges are not available to the the subprocess until a SET 
PROCESS /PRIVILEGE command or equivalent SYS$SETPRV call is performed 
in the subprocess to enable these privileges. 

If the calling image is installed with elevated privileges, it should disable 
those privileges around the call to LIB$SPAWN unless the environment of the 
subprocess is strictly controlled. Otherwise, there is a possibility of a security 
breach due to elevated privileges accidentally being made available to the user. 

If neither command-string nor input-file is present, command input will be 
taken from the parent terminal. If both command-string and input-file are 
present, the subprocess will first execute command-string and then read from 
input-file. If only command-string is specified, the command will be executed 
and the subprocess will be terminated. If input-file is specified, the subprocess 
will be terminated by either a LOGOUT command or an end-of-file. 

The subprocess does not inherit process-permanent files, nor routine or image 
context. No LOGIN.COM file is executed. 

Unless the NO WAIT flags bit is set, the caller’s process is put into hibernation 
until the subprocess completes. Because the caller’s process hibernates in 
supervisor mode, any user-mode ASTs queued for delivery to the caller will not be 
delivered until the caller reawakes. Control can also be restored to the caller by 
means of an ATTACH command or by a suitable call to LIB$ATTACH from the 
subprocess. 

This routine is supported for use only with the DCL command language 
interpreter. If used when the current CLI is MCR, the error status LIB$_ 
NOCLI will be returned. 
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If an image is run directly as a subprocess or as a detached process, there is no 
CLI present to perform this function. In such cases the error status LIB$_NOCLI 
is returned. 

Programs depending on embedded DCL commands may not function properly 
when run under other command language interpreters that may be supported by 
future versions of OpenVMS operating systems. 

See the OpenVMS DCL Dictionary for a complete description of the SPAWN 
command. 


Condition Values Returned 


SS$_N ORMAL 
SS$_ACCVIO 

SS$_DUPLNAM 


fac$_xxx 

LIB$_INVARG 

LIB$_INVSTRDES 

LIB$_NOCLI 


Routine successfully completed. 

Access violation. One of the string arguments to 
LIB$SPAWN could not be read, or completion- 
status-address could not be written. 

Duplicate process name. If the argument 
process-name was specified, it duplicated an 
existing process name. If process-name was 
omitted, LIB$SPAWN was unable to create a 
unique name for the subprocess. 

Other error trying to create subprocess. 

Invalid argument. The optional argument flags 
was specified and a bit other than bits 0 through 
5 was set. 

Invalid string descriptor. One of the string 
arguments had an invalid descriptor. 

No CLI present to perform function. The calling 
process did not have a CLI to perform the 
function, or the CLI did not support the request 
type. Note that an image run as a subprocess or 
detached process does not have a CLI. 


If an error is encountered while trying to create the subprocess, the status value 
for that error is returned by LIB$SPAWN. 


Example 


ISTAT=LIB$SPAWN ( ,, ,CLI$M_NOKEYPAD. > ' ) 

IF (.NOT. ISTAT) CALL LIB$STOP(%VAL(ISTAT)) 

This FORTRAN fragment shows a call to LIB$SPAWN from within a FORTRAN 
program. A subprocess is spawned taking input from SYS$INPUT and giving 
output to SYS$OUTPUT. The keypad state is not passed to the subprocess. A 
prompt string of “> ” is specified for the subprocess. 
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LIB$STAT_TIMER—Statistics, Return Accumulated Times and 

Counts 

The Statistics, Return Accumulated Times and Counts routine returns to its 
caller one of five available statistics accumulated since the last call to LIB$INIT 
TIMER. Unlike LIB$SHOW_TIMER, which formats the values for output, 
LIB$STAT_TIMER returns the value as an unsigned longword or quadword. 


Format 

LIB$STAT_TIMER code ,value-argument [,handle-address] 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Arguments 


code 

OpenVMS usage 

type 

access 

mechanism 


longword_signed 
longword integer (signed) 
read only 
by reference 


Code which specifies the statistic to be returned. The code argument contains 
the address of a signed longword integer that is this code. It must be an integer 
from 1 to 5. 


The following values are allowed for code. 


Value Statistic Returned 

1 Elapsed time (quadword, in system time format) 

2 CPU time (longword, in 10 millisecond increments) 

3 Buffered I/O (longword) 

4 Direct I/O (longword) 

5 Page faults (longword) 


value-argument 

OpenVMS usage user_arg 
type longword (unsigned) 

access write only 

mechanism by reference 

The statistic returned by LIB$STAT_TIMER. The value-argument argument 
contains the address of a longword or quadword that is this statistic. All statistics 
are longword integers except elapsed time, which is a quadword. 

See the OpenVMS System Services Reference Manual for more details on the 
system time format. 
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Description 


handle-address 

OpenVMS usage address 
type longword (unsigned) 

access read only 

mechanism by reference 

Pointer to a block of storage. The optional handle-address argument contains 
the address of an unsigned longword that is this pointer. 

If handle-address is specified, LIB$STAT_TIMER assumes that LIB$INIT_ 
TIMER has been called with the same value of handle-address. Handle- 
address is an optional argument. If it is not specified, LIB$STAT_TIMER uses 
internal storage. 


Only one of the five statistics is returned by each call to LIB$STAT_TIMER. The 
elapsed time is returned in the system quadword format. Therefore the receiving 
area should be eight bytes long. All other returned values are longwords. 

LIB$SHOW_TIMER and LIB$STAT_TIMER are relatively simple tools for testing 
the performance of a new application. Note that LIB$INIT_TIMER must be 
called prior to any calls to LIB$SHOW_TIMER or LIB$STAT_TIMER. 

To obtain more detailed information, use LIB$GETJPI (Get Job/Process 
Information) or the OpenVMS system service SYS$GETTIM (Get Time). 

The following summary shows the differences between LIB$SHOW_TIMER and 
LIB$STAT_TIMER. 


Code 

Statistic 

Format for 
LIB$SHOW_TIMER 

Format for 
LIB$STAT_TIMER 

1 

Elapsed real time 

hhhh:mm:ss.cc 

Quadword in system 
time format 

2 

Elapsed CPU time 

hhhh:mm:ss.cc 

Longword in 

10-millisecond 

increments 

3 

Count of buffered I/O 
operations 

nnnn 

Longword 

4 

Count of direct I/O 
operations 

nnnn 

Longword 

5 

Count of page faults 

nnnn 

Longword 


When you call LIB$INIT_TIMER, you must use the optional handle-address 
argument only if you want to keep several sets of statistics simultaneously. This 
argument points to a block in heap storage where the statistics are to be stored. 

You need to call LIB$FREE_TIMER only if you have specified handle-address 
in LIB$INIT_TIMER and you wish to deallocate all heap storage resources. In 
most cases, the implicit deallocation at program exit time will be sufficient. 
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Condition Values Returned 

SS$_NORMAL Routine successfully completed. 

LIB$_INVARG Invalid argument. Either code or handle- 

address is invalid. 


Example 


PROGRAM STATJTIMER(INPUT,OUTPUT); 

{ + } 

{ This Pascal example program demonstrates the use of 
{ LIB$STAT_TIMER. 

{-> 

TYPE 

BYTE = [BYTE] 0..255; 

WORD = [WORD] 0..65535; 

QUADWORD_SYSTEM_TIME = [QUAD] RECORD 
FIRST_LONGWORD : UNSIGNED; 

SECOND_LONGWORD : UNSIGNED; 

END; 

VAR 

ELAPSED_REAL_TIME : QUADWORD_SYSTEM_TIME; 

ELAPSED_STRING : VARYING [32] OF CHAR; 

PAGE_FAULT_COUNT : UNSIGNED; 

RETURNED_STATUS : UNSIGNED; 

[EXTERNAL] FUNCTION LIB$INIT_TIMER( 

HANDLE_ADR : [REFERENCE] UNSIGNED := %IMMED 0 
) : INTEGER; EXTERNAL; 

[EXTERNAL] FUNCTION LIB$STAT_TIMER( 

CODE : INTEGER; 

VALUE : [UNSAFE,REFERENCE] PACKED ARRAY [L..U:INTEGER] OF BYTE 

HANDLE_ADR : [REFERENCE] UNSIGNED := %IMMED 0 
) : INTEGER; EXTERNAL; 

[EXTERNAL] FUNCTION LIB$STOP( 

CONDITION_STATUS : [IMMEDIATE,UNSAFE] UNSIGNED; 

FAO_ARGS : [IMMEDIATE,UNSAFE,LIST] UNSIGNED 

) : INTEGER; EXTERNAL; 

[EXTERNAL] FUNCTION LIB$SYS_ASCTIM( 

OUT_LEN : [REFERENCE] WORD := %IMMED 0; 

VAR DST_STR : PACKED ARRAY [L..U:INTEGER] OF CHAR; 

USER_TIME : QUADWORD_SYSTEM_TIME := %IMMED 0; 

CNV_FLG : UNSIGNED := %IMMED 0 
) : INTEGER; EXTERNAL; 


BEGIN 

{ + } 

{ Call LIB$INIT_TIMER to initialize RTL internal counters. 

{-} 

RETURNED_STATUS := LIB$INIT_TIMER; 

IF NOT ODD(RETURNED_STATUS) 

THEN 

LIB$STOP(RETURNED_STATUS); 

{ + } 

{ Print a line of text to waste time. 

{-} 

WRITELN('Spend time to acquire elapsed real time and page faults'); 
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{+} 

{ Call LIB$STAT_TIMER to retrieve statistics values. 

{-} 

RETURNED_STATUS := LIB$STAT_TIMER(1,ELAPSED_REAL_TIME); 

IF NOT ODD(RETURNED_STATUS) 

THEN 

LIB$STOP(RETURNED_STATUS); 

RETURNED_STATUS := LIB$STAT_TIMER(5,PAGE_FAULT_COUNT); 

IF NOT ODD(RETURNED_STATUS) 

THEN 

LIB$STOP(RETURNED_STATUS); 

{ + } 

{ Print the statistics retrieved from LIB$STAT_TIMER. 

{-} 

WRITELN('Page fault count is ',PAGE_FAULT_COUNT:1); 

RETURNED_STATUS := LIB$SYS_ASCTIM( 

ELAPSED_STRING.LENGTH, 

ELAPSED_STRING.BODY, 

E LAP S E D_REAL_TIME, 

i); 

IF NOT ODD(RETURNED_STATUS) 

THEN 

LIB$STOP(RETURNED_STATUS); 

WRITELN('Elapsed real time is ',ELAPSED_STRING); 

END. 

This Pascal program demonstrates the use of LIB$STAT_TIMER. The output 
generated by this program is as follows: 

Spend time to acquire elapsed real time and page faults 

Page fault count is 22 

Elapsed real time is 00:00:00.61 
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LIB$STAT_VM—Return Virtual Memory Statistics 

The Return Virtual Memory Statistics routine returns to its caller one of six 
statistics available from calls to LIB$GET_VM/LIB$FREE_VM and LIB$GET_ 
VM_PAGE/LIB$FREE_VM_PAGE. Unlike LIB$SHOW_VM, which formats the 
values for output and displays them on SYS$OUTPUT, LIB$STAT_VM returns 
the statistic in the value-argument argument. Only one of the statistics is 
returned by each call to LIB$STAT_VM. 


Format 

UB$STAT_VM code ,value-argument 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Arguments 


code 

OpenVMS usage 

type 

access 

mechanism 


longword_signed 
longword integer (signed) 
read only 
by reference 


Code specifying which statistic is to be returned. The code argument contains 
the address of a signed longword integer that is this code. 


Code Statistic 

1 Number of successful calls to LIB$GET_VM 

2 Number of successful calls to LIB$FREE_VM 

3 Number of bytes allocated by LIB$GET_VM but not yet deallocated by 
LIB$FREE_VM 

5 Number of calls to LIB$GET_VM_PAGE 

6 Number of calls to LIB$FREE_VM_PAGE 

7 Number of VAX pages or AXP pagelets allocated by LIB$GET_VM_ 
PAGE but not yet deallocated by LIB$FREE_VM_PAGE 


Note that it is invalid to omit code or to give a code of 0 or 4. 

value-argument 

OpenVMS usage user_arg 
type longword (unsigned) 

access write only 

mechanism by reference 

Value of the statistic returned by LIB$STAT_VM. The value-argument 
argument contains the address of a signed longword integer that is this value. 
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Description 

LIB$STAT_VM returns to its caller one of six available statistics. Unlike 
LIB$SHOW_VM, which formats the values for output, LIB$STAT_VM returns 
the value to a location specified as an argument. 

Only one of the six statistics can be returned by one call to LIB$STAT_VM. Code 
must be one of six values described for LIB$SHOW_VM. A code value of 0 or 4 is 
invalid. 

Unlike LIB$SHOW_VM, which produces ASCII values for output, LIB$STAT_VM 
returns the value in binary form to a location specified as an argument. 

Condition Values Returned 

SS$_NORMAL Routine successfully completed. 

LIB$_INVARG Invalid argument. The value of code was not 

one of the values allowed by LIB$STAT_VM. 
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LIB$STOP—Stop Execution and Signal the Condition 

The Stop Execution and Signal the Condition routine generates a signal that 
indicates that an exception condition has occurred in your program. Exception 
conditions signaled by LIB$STOP cannot be continued from the point of the 
signal. 


Format 

LIB$STOP condition-value [,number-of-arguments] [,FAO-argument...] 

Returns 

LIB$STOP generates a signal and stops execution of the calling program. No 
condition values are returned. 


Arguments 

condition-value 

OpenVMS usage cond_value 
type longword (unsigned) 

access read only 

mechanism by value 

OpenVMS 32-bit condition value. The condition-value argument is an unsigned 
longword that contains this condition value. 

The OpenVMS Programming Concepts Manual explains the format of a condition 
value. 

number-of-arguments 

OpenVMS usage longword_signed 
type longword integer (signed) 

access read only 

mechanism by value 

Number of FAO arguments associated with condition-value. The optional 
number-of-arguments argument is a signed longword integer that contains this 
number. If omitted or specified as zero, no FAO arguments follow. 

FAO-argument 

OpenVMS usage varying_arg 
type unspecified 

access read only 

mechanism by value 

Optional FAO (formatted ASCII output) argument that is associated with the 
specified condition value. 

The OpenVMS Programming Concepts Manual explains the message format. 
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Description 

LIB$STOP is called whenever your program must indicate an exception condition 
because it is impossible to continue execution or return a status code to the 
calling program. 

LIB$STOP scans the stack frame by frame, starting with the most recent frame, 
calling each established handler (see the OpenVMS Programming Concepts 
Manual). LIB$STOP guarantees that control will not return to the caller. 

The LIB$STOP argument list, the Program Counter (PC) and Processor Status 
Longword (PSL on OpenVMS VAX systems, PS on OpenVMS AXP systems) of the 
caller are appended to build the signal argument vector. 

The severity of condition-value is forced to SEVERE before each call to a 
handler. 

If any handler attempts to continue by returning a success completion code, 
the error message ATTEMPT TO CONTINUE FROM STOP is printed and your 
program exits. 

If the handler called by LIB$STOP in turn calls SYS$UNWIND, control will not 
return to LIB$STOP’s caller, thus changing the program flow. A handler can also 
modify the saved copy of R0/R1 in the mechanism vector, changing registers RO 
and R1 after the stack has been unwound. If a handler does neither of these 
things, then all registers including R0/R1 and the hardware condition codes are 
preserved 1 . 

The only way a handler can prevent the image from exiting after a call to 
LIB$STOP is to unwind the stack using the SYS$UNWIND system service. 

Condition Values Returned 

None. 


Example 


10 EXTERNAL LONG FUNCTION LIB$RESERVE_EF 
DECLARE LONG RET_STATUS 

RET_STATUS = LIB$RESERVE_EF( 2% ) 

IF (RET_STATUS AND 1%) = 0% THEN 

CALL LIB$STOP( RET_STATUS BY VALUE ) 

END IF 

PRINT "Event flag 2 reserved successfully" 

END 

This BASIC example program uses LIB$STOP to stop executing if an error is 
signaled. This BASIC program tries to reserve an event flag that is not accessable 
to user programs, thus ensuring that an error will be signaled. 

The output generated by this BASIC program is as follows: 

%LIB-F-EF_ALRRES, event flag already reserved 
%TRACE-F-TRACEBACK, symbolic stack dump follows 

module name routine name line rel PC abs PC 

2822XBLST$MAIN 2822XBLST$MAIN 6 00000044 00000644 


1 On AXP systems, OpenVMS AXP instructions perform the equivalent operation. 
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LIB$SUB_TIMES—Subtract Two Quadword Times 

The Subtract Two Quadword Times routine subtracts two OpenVMS internal- 
time-format times. 


Format 


LIB$SUB_TIMES timel ,time2 ,resultant-time 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Arguments 


timel 

OpenVMS usage 

type 

access 

mechanism 


date_time 

quadword (unsigned) 
read only 
by reference 


First time, from which LIB$SUB_TIMES subtracts the second time. The timel 
argument is the address of an unsigned quadword containing this time. Timel 
must represent a later or equal time or a longer or equal time interval than 
time2. Timel may be either absolute time or delta time as long as time2 is of 
the same type. If timel and time2 are of different types, timel must be the 
absolute time. 


time2 

OpenVMS usage date_time 
type quadword (unsigned) 

access read only 

mechanism by reference 

Second time, which LIB$SUB_TIMES subtracts from the first time. The time2 
argument is the address of an unsigned quadword containing this time. Time2 
must represent an earlier or equal time or a shorter or equal time interval than 
timel. Time2 may be either absolute time or delta time as long as timel is of 
the same type. If time2 and timel are of different types, time2 must be the 
delta time. 


resultant-time 

OpenVMS usage date_time 
type quadword (unsigned) 

access write only 

mechanism by reference 

The result of subtracting time2 from timel. The resultant-time argument is 
the address of an unsigned quadword containing the result. If both timel and 
time2 are delta times, then resultant-time is a delta time. If both timel and 
time2 are absolute times, then resultant-time is a delta time. If timel is an 
absolute time and time2 is a delta time, then resultant-time is an absolute 
time. 
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Description 

LIB$SUB_TIMES subtracts two OpenVMS internal times. The second time, 
specified by time2, is subtracted from timel. The following table shows the only 
combinations of times you can subtract: 


Timel 

Time2 

Subtraction 

Resultant-Time 

delta 

delta 

timel—time2 

delta 

absolute 

absolute 

timel—time2 

delta 

absolute 

delta 

timel—time2 

absolute 


Delta times must be less than 10,000 days. 

OpenVMS does not allow a delta time to be 0 or negative. Therefore, if timel 
and time2 are equal, resultant-time cannot be 0. Instead, resultant-time is 
represented by .1 of one microsecond (the smallest interval of time recognized by 
the OpenVMS operating system). This interval is shown as “0 00:00:00.00” when 
formatted by the standard techniques. 


Condition Values Returned 

LIB$_N ORMAL 

LIB$_IVTIME 

LIB$_NEGTIM 

LIB$_WRONUMARG 

LIB$_INVARGORD 


Normal successful completion. 
Invalid time. 

Negative time computed. 
Incorrect number of arguments. 
Invalid ordering of arguments. 
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LIBSSUBX—Multiple-Precision Binary Subtraction 

The Multiple-Precision Binary Subtraction routine performs subtraction on signed 
two’s complement integers of arbitrary length. 

Format 

LIB$SUBX minuend-array ,subtrahend-array .difference-array [.array-length] 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Arguments 

minuend-array 

OpenVMS usage vector_longword_signed 
type unspecified 

access read only 

mechanism by reference, array reference 

Minuend; a multiple-precision, signed two’s complement integer. The minuend- 
array argument is the address of an array of signed longword integers that 
contains the minuend. 

subtrahend-array 

OpenVMS usage vector_longword_signed 
type unspecified 

access read only 

mechanism by reference, array reference 

Subtrahend; a multiple-precision, signed two’s complement integer. The 
subtrahend-array argument is the address of an array of signed longword 
integers that contains the subtrahend. 

difference-array 

OpenVMS usage vector_longword_signed 
type unspecified 

access write only 

mechanism by reference, array reference 

Difference; a multiple-precision, signed two’s complement integer result. The 
difference-array argument is the address of an array of signed longword 
integers that contains the difference. 

array-length 

OpenVMS usage longword_signed 
type longword integer (signed) 

access read only 

mechanism by reference 


cond_value 
longword (unsigned) 
write only 
by value 
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Length in longwords of the arrays to be operated on by LIB$SUBX. The array- 
length argument contains the address of a signed longword integer that is this 
length. Array-length must not be negative. The default length is 2 units. 


Description 

LIB$SUBX performs subtraction on signed two’s complement integers of arbitrary 
length. The integers are located in arrays of longwords. The higher addresses 
contain the higher-precision parts of the values. The highest-addressed longword 
contains the sign and 31 bits of precision. The remaining longwords contain 32 
bits of precision in each. The number of longwords to be operated on is given by 
the optional argument, array-length. The default length is 2, which corresponds 
to the OpenVMS quadword data type. 


Condition Values Returned 

SS$_N ORMAL 
SS$_INTOVF 

LIB$_INVARG 


Routine successfully completed. 

Integer overflow. The result is correct, except 
that the sign bit is lost. 

Invalid argument. Length is negative. The 
output array is unchanged. 


Example 


c+ 

C This FORTRAN example program demonstrates the use of LIB$SUBX. 

C- 

INTEGER A(2),B(2),C(2),RETURN 
C+ 

C Let "A" have the value 72057594037927937 = '1000000000000001'x. 

C Let "B" have the value 4294967295 = 'OOOOOOOOFFFFFFFF'x. 

C- 

A(1) = '00000001'x 
A(2) = '10000000'x 
B(1) = 'FFFFFFFF'x 
B(2) = '00000000'x 

c+ 

C Then "A" - "B" is 72057589742960642. 

C- 

RETURN = LIB$SUBX(A,B,C) 

TYPE ' ' 

TYPE *,'Let A = 72057594037927937 and B = 4294967295.' 

TYPE *,'Then C = A - B = 72057589742960642.' 

TYPE 2,C(2),C(1) 

2 FORMAT(' 72057589742960642 is represented as ',1H',Z8,Z8,3H'x.) 

TYPE *, 51HThat is, C(2) = '0FFFFFFF'x and C(l) = '00000002'x. 

END 

This FORTRAN example demonstrates how to call LIB$SUBX. The output 
generated by this program is as follows: 

Let A = 72057594037927937 and B = 4294967295. 

Then C = A - B = 72057589742960642. 

72057589742960642 is represented as ' FFFFFFF 2'x. 

That is, C(2) = '0FFFFFFF'x and C(1) = '00000002'x. 
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LIB$SYS_ASCTIM—Invoke $ASCTIM to Convert Binary Time to ASCII 

String 

The Invoke $ASCTIM to Convert Binary Time to ASCII String routine calls the 
system service $ASCTIM to convert a binary date and time value, returning the 
ASCII string using the semantics of the caller’s string. 

Format 

LIB$SYS_ASCTIM [resultant-length] ,time-string [,user-time] [,flags] 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Arguments 

resultant-length 

OpenVMS usage word_unsigned 
type word (unsigned) 

access write only 

mechanism by reference 

Number of bytes written into time-string, not counting padding in the case of a 
fixed-length string. The resultant-length argument contains the address of an 
unsigned word integer that is this number. 

If the input string is truncated to the size specified in the time-string descriptor, 
resultant-length is set to this size. Therefore, resultant-length can always be 
used by the calling program to access a valid substring of time-string. 

time-string 

OpenVMS usage time_name 
type character string 

access write only 

mechanism by descriptor 

Destination string into which LIB$SYS_ASCTIM writes the ASCII time string. 
The time-string argument contains the address of a descriptor pointing to the 
destination string. 

user-time 

OpenVMS usage date_time 
type quadword (unsigned) 

access read only 

mechanism by reference 

Value that LIB$SYS_ASCTIM converts to ASCII string form. The user-time 
argument contains the address of a signed quadword integer that is this value. 

If zero or no address is specified, the current system date and time are returned. 
A positive value represents an absolute time. A negative value represents a delta 
time. Delta times must be less than 10,000 days. 
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flags 

OpenVMS usage mask_longword 
type longword (unsigned) 

access read only 

mechanism by reference 

Conversion indicator specifying which date and time fields LIB$SYS_ASCTIM 
should return. The flags argument is the address of an unsigned bit mask that 
contains this conversion indicator. 

A value of 1 causes only the hour, minute, second, and hundredths of a second to 
be returned, depending on the length of the buffer. A value of zero (the default) 
causes the full date and time to be returned, depending on the length of the 
buffer. 

The results of specifying some possible combinations for the values of the flags 
and time-string arguments are shown below: 


Time Value 

Time-string 

Length 

Flags 

Value 

Information Returned 

Absolute 

23 

0 

Date and time 

Absolute 

12 

0 

Date 

Absolute 

11 

1 

Time 

Delta 

16 

0 

Days and time 

Delta 

11 

1 

Time 


Argument flags is passed to LIB$SYS_ASCTIM by reference and is changed to 
value for use by $ASCTIM. 


Description 

See the OpenVMS System Services Reference Manual for a complete description of 
$ASCTIM. 


Condition Values Returned 

SS$_N ORMAL 
LIB$_STRTRU 

LIB$_FATERRLIB 


LIB$_IN SVIRMEM 

LIB$_INVSTRDES 

SS$_IVTIME 


Routine successfully completed. 

Routine successfully completed, but the source 
string was truncated. 

Fatal internal error. An internal consistency 
check has failed. This usually indicates an 
internal error in the Run-Time Library and 
should be reported to Digital in a Software 
Performance Report (SPR). 

Insufficient virtual memory. A call to LIB$GET_ 
VM has failed because your program has 
exceeded the image quota for virtual memory. 

Invalid string descriptor. A string descriptor has 
an invalid value in its DSC$B_CLASS field. 

The specified delta time is greater than or equal 
to 10,000 days. 
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LIB$SYS_FAO—Invoke $FAO System Service to Format Output 

The Invoke $FAO System Service to Format Output routine calls $FAO, returning 
a string in the semantics you provide. If called with other than a fixed-length 
string for output, the length of the resultant string is limited to 256 bytes and 
truncation will occur. 

Format 

LIB$SYS_FAO character-string, [resultant-length] ,resultant-string [,directive-argument ,...] 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Arguments 

character-string 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

ASCII control string, consisting of the fixed text of the output string and FAO 
directives. The character-string argument contains the address of a descriptor 
pointing to this control string. 

resultant-length 

OpenVMS usage word_unsigned 
type word (unsigned) 

access write only 

mechanism by reference 

Length of the output string. The resultant-length argument contains the 
address of an unsigned word integer that is this length. 

resultant-string 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor 

Fully formatted output string returned by LIB$SYS_FAO. The resultant-string 
argument contains the address of a descriptor pointing to this output string. 

directive-argument 

OpenVMS usage varying_arg 
type unspecified 

access read only 

mechanism unspecified 


cond_value 
longword (unsigned) 
write only 
by value 
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Directive argument contained in longwords. Depending on the directive, a 
directive-argument argument can be a value to be converted, the address of the 
string to be inserted, or a length or argument count. The passing mechanism for 
each of these arguments should be the one expected by the $FAO system service. 


Description 

See the OpenVMS System Services Reference Manual for a complete description of 
$FAO. 


Condition Values Returned 

SS$_N ORMAL 
SS$_BUFFEROVF 

LIB$_STRTRU 
SS$_BADPARAM 
LIB$_IN SVIRMEM 
LIB$_INVSTRDES 


Routine successfully completed. 

Successfully completed, but the formatted output 
string overflowed the output buffer and was 
truncated. 

Success, but the source string was truncated on 
copy. 

An invalid directive was specified in the FAO 
control string. 

Insufficient virtual memory to allocate dynamic 
string. 

Invalid string descriptor. A string descriptor has 
an invalid value in its DSC$B_CLASS field. 
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LIB$SYS_FAOL—Invoke $FAOL System Service to Format Output 

The Invoke $FAOL System Service to Format Output routine calls the system 
service routine $FAOL, returning the string in the semantics you provide. If 
called with other than a fixed-length string for output, the length of the resultant 
string is limited to 256 bytes and truncation will occur. 

Format 

LIB$SYS_FAOL character-string [,resultant-length] ,resultant-string .directive-argument-address 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Arguments 

character-string 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

ASCII control string, consisting of the fixed text of the output string and FAO 
directives. The character-string argument contains the address of a descriptor 
pointing to this control string. 

resultant-length 

OpenVMS usage word_unsigned 
type word (unsigned) 

access write only 

mechanism by reference 

Length of the output string. The resultant-length argument contains the 
address of an unsigned word integer that is this length. 

resultant-string 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor 

Fully formatted output string returned by LIB$SYS_FAOL. The resultant-string 
argument contains the address of a descriptor pointing to this output string. 

directive-argument-address 

OpenVMS usage address 
type longword (unsigned) 

access read only 

mechanism unspecified 


cond_value 
longword (unsigned) 
write only 
by value 
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Directive arguments. The directive-argument-address arguments are 
contained in an array of unsigned longword directive arguments. Depending 
on the directive, a directive-argument-address argument can be a value to be 
converted, the address of the string to be inserted, or a length or argument count. 
The passing mechanism for each of these arguments should be the one expected 
by the $FAOL system service. 


Description 

See the OpenVMS System Services Reference Manual for a complete description of 
$FAOL. 


Condition Values Returned 

SS$_N ORMAL 
SS$_BUFFEROVF 

LIB$_STRTRU 

SS$_BADPARAM 

LIB$_INSVIRMEM 

LIB$_INVSTRDES 


Routine successfully completed. 

Successfully completed, but the formatted output 
string overflowed the output buffer and was 
truncated. 

Success, but the source string was truncated on 
copy. 

An invalid directive was specified in the FAO 
control string. 

Insufficient virtual memory to allocate dynamic 
string. 

Invalid string descriptor. A string descriptor has 
an invalid value in its DSC$B_CLASS field. 
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LIB$SYS_GETMSG—Invoke $GETMSG System Service to Get 

Message Text 

The Invoke $GETMSG System Service to Get Message Text routine calls the 
System Service $GETMSG and returns a message string into destination-string 
using the semantics of the caller’s string. 

Format 

UB$SYS_GETMSG message-id [,message-length] ,destination-string [,flags] [,unsigned-resultant-array] 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access write only 

mechanism by value 

Arguments 

message-id 

OpenVMS usage identifier 
type longword (unsigned) 

access read only 

mechanism by reference 

Message identification to be retrieved by LIB$SYS_GETMSG. The message-id 
argument contains the address of an unsigned longword integer that is this 
message identification. 

message-length 

OpenVMS usage word_unsigned 
type word integer (unsigned) 

access write only 

mechanism by reference 

Number of characters written into destination-string, not counting padding in 
the case of a fixed-length string. The message-length argument contains the 
address of an unsigned word integer that is this number. 

If the input string is truncated to the size specified in the destination-string 
descriptor, message-length is set to this size. Therefore, message-length can 
always be used by the calling program to access a valid substring of destination¬ 
string. 

destination-string 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor 

Destination string. The destination-string argument contains the address of 
a descriptor pointing to this destination string. LIB$SYS_GETMSG writes the 
message that has been returned by $GETMSG into destination-string. 
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flags 

OpenVMS usage maskjongword 
type longword (unsigned) 

access read only 

mechanism by reference 

Four flag bits for message content. The flags argument is the address of an 
unsigned longword that contains these flag bits. The default value is a longword 
with bits zero through 3 set to 1. The flags argument is passed to LIB$SYS_ 
GETMSG by reference and changed to value for use by $GETMSG. 

Bit numbers, their values, and corresponding descriptions are listed below. 


Bit 

Value 

Description 

0 

1 

Include text of message 


0 

Do not include text of message 

1 

1 

Include message identifier 


0 

Do not include message identifier 

2 

1 

Include severity indicator 


0 

Do not include severity indicator 

3 

1 

Include facility name 


0 

Do not include facility name 


unsigned-resultant-array 

OpenVMS usage unspecified 

type unspecified 

access write only 

mechanism by reference, array reference 

A 4-byte array to receive message-specific information. The unsigned-resultant- 
array argument contains the address of this array. 

The contents of this 4-byte array are as follows: 


Byte Contents 

0 Reserved 

1 Count of FAO arguments 

2 User value 

3 Reserved 


Description 

LIB$SYS_GETMSG calls the $GETMSG system service and returns a message 
string using the semantics of the caller’s string. Note that, in order to retrieve a 
message string for a LIB$ facility message, you must include the file $LIBDEF in 
your program. 

See the OpenVMS System Services Reference Manual for a more complete 
description of $GETMSG. 
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Condition Values Returned 

SS$_N ORMAL 
SS$_BUFFEROVF 


SS$_MSGN OTFND 

LIB$_STRTRU 

LIB$_FATERRLIB 

LIB$_INSVIRMEM 

LIB$_INVSTRDES 


Routine successfully completed. 

Successfully completed, but the resultant 
string overflowed the buffer provided and was 
truncated. 

Successfully completed, but the message code 
does not have an associated message on file. 

Successfully completed, but the source string was 
truncated. 

Fatal internal error. 

Insufficient virtual memory. 

Invalid string descriptor. 
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LIB$TPARSE/LIB$TABLE_PARSE—Table-Driven Finite-State Parser 



The Table-Driven Finite State Parser routine is a general-purpose, table-driven 
parser implemented as a finite-state automaton, with extensions that make 
it suitable for a wide range of applications. It parses a string and returns a 
message indicating whether or not the input string is valid. 

LIB$TPARSE performs this function on OpenVMS VAX systems. ♦ 

LIB$TABLE_PARSE performs this function on OpenVMS AXP systems and 
is available only on OpenVMS AXP systems. LIB$TPARSE is available in 
translated form on OpenVMS AXP systems. LIB$TABLE_PARSE differs from 
LIB$TPARSE only in the way that user specified action routines are called. ♦ 


Format 

LIB$TPARSE/LIB$TABLE_PARSE argument-block ,state-table ,key-table 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Arguments 


argument-block 

OpenVMS usage 

type 

access 

mechanism 


unspecified 
unspecified 
modify 
by reference 


LIB$T[ABLE_]PARSE argument block. The argument-block argument contains 
the address of this argument block. 


The LIB$T[ABLE_]PARSE argument block contains information about the state 
of the parse operation. It becomes the argument list presented to all action 
routines. 

Figure LIB—22 shows the format of the argument block. 
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Figure LIB-22 LIB$T[ABLE_]PARSE Argument Block 

TPA$L_COUNT: 

TPA$L_OPTIONS: 

TPA$L_STRINGCNT: 

TPA$L_STRINGPTR: 

TPA$L__TOKENCNT: 

TPA$L__TOKENPTR: 

TPA$B_CHAR: 

TPA$L_NUMBER: 

TPA$L_PAR AM: 


TPA$K_COUNTO = 8 


Flag Bits 


Length of Input String 


Pointer to Input String 


Length of Current Token 


Pointer to Current Token 


Character 


Unused 


Binary Value of Numeric Token 


Argument Supplied by User 


ZK-1929-GE 

Note that the high byte of the longword field TPA$L_OPTIONS is TPA$B_ 
MCOUNT. The fields of the argument block are explained in detail in the section 
entitled “The LIB$T[ABLE_]PARSE Argument Block.” 

state-table 

OpenVMS usage unspecified 
type unspecified 

access read only 

mechanism by reference 

Starting state in the state table. The state-table argument is the address of this 
starting state. 

Usually, the name appearing as the first argument of the $INIT_STATE macro is 
used. 

key-table 

OpenVMS usage unspecified 
type unspecified 

access read only 

mechanism by reference 

Keyword table. The key-table argument is the address of this keyword table. 

This name must be the same as that which appeared as the second argument of 
the $INIT_STATE macro. It is called with the address of an argument block, the 
address of a state table, and the address of a keyword table. The input string is 
specified as part of the argument block. 
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Description 

LIB$T[ABLE_]PARSE analyzes an input string according to a set of states and 
transitions presented in a state table to determine whether the input string is 
valid according to the rules you have defined for the input language. 

The following sections explain in detail how LIB$T[ABLE_]PARSE works and 
how to call it from both assembly and high-level languages. 

1. “How LIB$T[ABLE_]PARSE Works” describes the data structures used by 
LIB$T[ABLE_]PARSE and how LIB$T[ABLE_]PARSE operates on them. 

2. “Coding and Using a Simple State Table” shows you how to construct and use 
a simple state table. 

3. “Using Advanced LIB$TPARSE Features” explains how to use subexpressions, 
abbreviations, action routines, and other advanced features. 

4. “State Table Object Representation” includes information of interest to the 
low-level language programmer, such as the state table object representation. 

How LIB$T[ABLE_]PARSE Works 

There are three parts to any parsing operation. 

1. The string to be parsed. LIB$T[ABLE_]PARSE accepts the input string as 
part of an argument block that contains additional information about the 
state of the parse—how much of the string has not been interpreted, what the 
current token is, and so forth. See the section entitled “The LIB$T[ABLE_ 
]PARSE Argument Block.” 

2. The set of characters from which the input string is chosen, called the 
alphabet of your language. LIB$T[ABLE_]PARSE recognizes the ASCII 
character set and provides symbolic names for the most common combinations 
of ASCII characters—alphabetic and alphanumeric strings, OpenVMS 
symbols, numbers, and so on. See the section entitled “The Alphabet of 
LIB$TPARSE/LIB$TABLE_PARSE.” 

3. The rules which govern how the alphabet is used—in other words, the 
language’s syntax. You specify these rules in the state tables. (In a 
LIB$T[ABLE_]PARSE state table, each state is simply a list of the transitions 
to other states.) See the section entitled “The State Tables.” 

LIB$T[ABLE_]PARSE reads the input string from left to right, dividing it 
into a set of tokens— substrings to be treated as logical entities. By default, 
LIB$T[ABLE_]PARSE treats blanks as invisible separators; it takes all characters 
up to the next blank as a single token. You can use the TPA$V_BLANKS flag 
in the argument block to cause LIB $T[ABLE_]PARSE to interpret the tokens 
differently; see the section entitled “Blanks in the Input String.” 

LIB$T[ABLE_]PARSE evaluates the transitions in the order in which they appear 
in the state, which corresponds to the order in which they were written in the 
source program. Each token is then evaluated against each possible transition in 
the current state. If it does not match, LIB$T[ABLE_]PARSE attempts to match 
the next transition, until it runs out of transitions in the state. 

Each transition specifies what constitutes a valid token, what state is to be 
entered next, whether an action routine is to be called, and whether information 
is to be stored in a mask or mask-adr argument. By default, the next state 
is the state that follows the current state in the state table. No action routines 
are called, and no information is stored. LIB$T[ABLE_]PARSE also allows 
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subexpression calls, which can change the order in which transitions are 
accepted; see the section entitled “Using Subexpressions.” Action routines can 
also change the order in which transitions are accepted. The section entitled 
“Action Routines” explains how LIB$T[ABLE_]PARSE processes action routines. 

LIB$T[ABLE_]PARSE reads the input string, interprets the transitions in the 
state table, and calls the action routines (if any) until: 

1. It executes a transition to TPA$_EXIT (the string is valid) at main level (that 
is, while it is not processing a subexpression call). It returns with the value 
SS$_NORMAL. 

2. A transition or action routine requests that LIB$T[ABLE_]PARSE consider 
the string invalid by specifying a transition to TPA$_FAIL at main 
level. LIB$TPARSE/LIB$TABLE_PARSE returns with the value LIB$_ 
SYNTAXERR or an alternate failure status returned by an action routine. 

3. An error occurs at main level. The error can be either: 

• A syntax error. All transitions in the current state fail to match the 
current token. LIB$T[ABLE_]PARSE returns LIB$_SYNTAXERR or an 
alternate failure status returned by an action routine. 

• A state table format error. One of your state table entries is invalid. 
LIB$T[ABLE_]PARSE returns LIB$_INVTYPE. 

LIB$T[ABLE_]PARSE generates no signals and establishes no condition handler; 
action routines can signal through LIB$T[ABLE_]PARSE back to the calling 
program. 

The sections that follow describe each of these parts in more detail. 

The Alphabet of LIB$TPARSE/LIB$TABLE_PARSE LIB$T[ABLEJPARSE 
recognizes strings made up of elements of the ASCII character set. It provides 
all the basic building blocks needed for constructing a grammar using the 
ASCII character set. There are also symbols that represent the more complex 
constructions found in programming and command language grammar. 

Table LIB-7 shows the alphabet of LIB$T[ABLE_]PARSE. 


Table LIB-7 The Alphabet of LIB$T[ABLE_]PARSE 


Symbol Character Matched 


'X' 


TPA$_ANY 

TPA$_ALPHA 

TPA$_DIGIT 


The particular ASCII character. In a state table, it is 
expressed by enclosing the character in single quotation 
marks. The character can be any member of the 8-bit ASCII 
code set. LIB$T[ABLE_]PARSE does not consider uppercase 
and lowercase alphabetic characters and codes with different 
values in bit 7 to be equivalent. 

Any single character. (The actual matching character is 
placed in the TPA$B_CHAR field of the argument block.) 

Any alphabetic character, which includes the DEC 
multinational character set. 

Any numeric character, that is, 0 through 9. 

(continued on next page) 
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Table LIB-7 (Cont.) The Alphabet of LIB$T[ABLE_]PARSE 
Symbol Character Matched 


TPA$_STRIN G 


TPA$_SYMBOL 


TPA$_BLANK 

TPA$_DECIMAL 


TPA$_OCTAL 


TPA$_HEX 


TPA$_FILESPEC 


TPA$_UIC 


Any string of one or more alphanumeric characters, that 
is, uppercase or lowercase A through Z, and the numeric 
characters 0 through 9. The string can be any length. It is 
bounded on the right by the first nonalphanumeric character 
or by the end of the string. A descriptor of the matching 
string is available in the argument block. 

Any string of one or more characters of the standard 
OpenVMS symbol constituent set, that is, uppercase and 
lowercase A through Z and all DEC multinational characters, 
in addition to the dollar sign ($), and the underscore (_). 
The string is bounded on the right by some character not in 
the symbol constituent set (usually a blank), or by the end of 
the string. 

Any string of one or more blanks and/or tabs. 

Any decimal number (that is, any string of one or more digits 
0 through 9) whose magnitude is less than 2 32 . The binary 
value of the number, converted in decimal radix, is placed in 
the argument block. 

Any octal number (that is, any string of one or more digits 
0 through 7) whose magnitude is less than 2 32 . The binary 
value of the number, converted in octal radix, is placed in the 
argument block. 

Any hexadecimal number (that is, any string of one or more 
digits 0 through 9, A through F) whose magnitude is less 
than 2 32 . The binary value of the number, converted in 
hexadecimal radix, is placed in the argument block. 

Any string that constitutes a valid OpenVMS file 
specification. The string is bounded on the right by the first 
character that either is not a file specification constituent 
character or would cause the string to violate the syntax 
rules of a file specification. 

Any string that constitutes a valid OpenVMS numerical UIC 
specification, bounded by square brackets or angle brackets. 
The binary value of the UIC, converted in octal radix, is 
placed in the argument block. The wildcard character (*) 
is permitted in the group and/or member fields; its presence 
results in that field being set to its largest possible value in 
the binary value. 

(continued on next page) 
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Table LIB-7 (Cont.) The Alphabet of LIB$T[ABLEJPARSE 

Symbol Character Matched 

TPA$_IDENT Any string that constitutes a valid OpenVMS identifier. 

Identifiers may be given as numerical UICs according to the 
rules for TPA$_UIC, or as alphabetic identifier names that 
appear in the system’s rights database. The binary value of 
the identifier, converted in either octal or hexadecimal radix 
or by lookup in the system rights database, is placed in the 
argument block. Identifiers may be entered in any of the 
following forms: 

[n,m] <n,m> [name1,name2] <name1,name2> [name] <name> name %Xhex- 
value (any above instance of number or name may also be *) 

'keyword' The string of characters enclosed in single quotation marks. 

A keyword can consist of one or more characters of the 
OpenVMS symbol constituent set, that is, uppercase and 
lowercase A through Z, the numerals 0 through 9, the dollar 
sign ($), and the underscore (_). Uppercase and lowercase 
alphabetics are treated as different characters. A state table 
can contain up to 220 keywords. The keyword is bounded on 
the right by a character not in the symbol constituent set, 
or by the end of the string. Keywords that are one character 
in length are expressed in the form ' x*' to distinguish 
them from the single-character symbol ( 'x' ). They must be 
differentiated since they are not the same in operation. 

For example, in the input string AB+C, the single character 
'A' would match the first character of this string, whereas 
the keyword ' A*' would not, since B in the string is in the 
symbol constituent set. 

TPA$_LAMBDA The empty string (always matches). As it executes the 
transition, LIB$T[ABLE_JPARSE does not remove any 
characters from the input string. LAMBDA transitions are 
useful in getting action routines called under otherwise 
awkward circumstances, providing unconditional GOTOs to 
link portions of a state table together, and providing default 
actions in certain cases. 

TPA$_EOS The end of the input string. 

(continued on next page) 
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Table LIB-7 (Cont.) The Alphabet of LIB$T[ABLE_]PARSE 
Symbol Character Matched 

label A subexpression. LIB$T[ABLE_]PARSE enters the state 

table at the indicated label and executes state transitions 
until a final state is entered. If the subexpression fails 
(that is, if it encounters a syntax error in the input string), 
the input string is backed up to the point at which the 
subroutine started, and the subexpression simply fails to 
match. The subexpression facility permits complex syntactic 
constructs that appear in many places in grammar to appear 
only once in the state table. It also permits a degree of 
nondeterministic or pushdown parsing with a parser that 
is otherwise deterministic and finite-state. See the section 
entitled “Using Subexpressions.” 


A theoretical finite-state machine simultaneously compares the symbol types 
given by all of the transitions out of a particular state with the current token. 
The machine then executes the one transition whose symbol type matches. Since 
an ordinary sequential computer executes LIB$TPARSE/LIB$TABLE_PARSE, 
it evaluates the transitions sequentially and executes the first transition whose 
symbol type matches. Note also that the set of symbol types implemented by 
LIB$T[ABLE_]PARSE matches overlapping sets of tokens. For example, the 
token 123 could match TPA$_DECIMAL, TPA$_OCTAL, TPA$_STRING, or one of 
several other symbol types. 

Thus if there is more than one transition out of a state whose symbol types 
match overlapping sets of tokens, you must order the symbol types carefully. 

For example, the TPA$_SYMBOL symbol type matches all keyword strings. In 
general, LIB$T[ABLE_JPARSE will never execute keyword transitions appearing 
in a state following a TPA$_SYMBOL. It is best, therefore, to order transitions of 
different types in order of increasing generality, as follows: 

' keyword' 

'X' 

TPA$_EOS 

TPA$_ALPHA 

TPA$_DIGIT 

TPA$_BLANK 

TPA$_OCTAL 

TPA$_DECIMAL 

TPA$_HEX 

TPA$_STRIN G 

TPA$_SYMBOL 

TPA$_UIC 

TPA$_IDENT 

TPA$_FILE SPE C 

TPA$_ANY 

TPA$_LAMBDA 

Note that subexpressions are not in this list; their placement depends on the 
symbol types recognized within the subexpression. If you use action routines to 
reject certain transitions, you can change the order in which that symbol type 
is placed in this order. In any case, however, LIB$TPARSE/LIB$TABLE_PARSE 
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will execute the first transition listed in a state that is permitted to match the 
leftmost portion of the input string. 

The LIB$T[ABLE_]PARSE Argument Block LIB$T[ABLEJPARSE finds the 
input string through the argument block. This argument block is the impure data 
base upon which LIB$T[ABLE_]PARSE operates. That is, it is a set of variable 
data that can be written as well as read. It contains information about the 
string to be parsed, option flags for LIB$TPARSE/LIB$TABLE_PARSE, and data 
about the current token. When LIB$T[ABLE_]PARSE calls an action routine, the 
argument block becomes the argument list of the action routine, allowing efficient 
reference by the routine. 

The fields in the argument block have symbolic names. Assembly language 
programs can define these names by invoking the macro $TPADEF (automatically 
loaded from the system macro library). The field names define the byte offset of 
the field from the start of the argument block. This includes the bit fields ($V_ 
names). In addition, bit mask values ($M_names) are available for the bit fields. 

The same field names are available to BLISS programs from the system macro 
library SYS$LIBRARY:STARLET.L32. Each name (except for the $M_names) 
is defined as a fixed-reference macro that operates on a byte-based block. The 
$M_names are defined as literals. 

Table LIB-8 contains the fields of the argument block. 

Table LIB-8 Argument Block Fields 
Symbol Meaning 

TPA$L_COUNT A longword containing the number of longwords that make 

up the rest of the argument block. This longword functions 
as the argument count when the argument block becomes the 
argument list to an action routine. This field must contain the 
value TPA$K_COUNTO (whose numeric value is 8). 

TPA$L_OPTIONS A longword containing various option and flag bits. The defined 

flags are as follows: 

TPA$V_BLANKS — Setting this bit causes LIB$T[ABLE_ 
JPARSE to process blanks and tabs explicitly, rather than 
treating them as invisible separators (see the section entitled 
“Blanks in the Input String” on blank processing). 

TPA$V_ABBRFM — Setting this bit allows keywords to be 
abbreviated to any length. If an abbreviated keyword string 
is ambiguous, the first eligible transition listed in the state 
matches it. 

TPA$V_ABBREV — Setting this bit allows keywords to be 
abbreviated to the shortest length that is unambiguous in 
that state. (See the section entitled “Abbreviating Keywords” 
on keyword abbreviation.) 


(continued on next page) 
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Table LIB-8 (Cont.) Argument Block Fields 

Symbol Meaning 


TPA$B_MCOUNT 


TPA$L_STRIN GCNT 
TPA$L_STRIN GPTR 


TPA$L_TOKENCNT 

TPA$L_TOKENPTR 


TPA$B_CHAR 


TPA$V_AMBIG — LIB$T[ABLE JPARSE sets this bit when 
it has detected an ambiguous keyword string in the current 
state. 

A byte containing the minimum number of characters in the 
abbreviation of a keyword. If zero, abbreviations are not 
allowed. Preventing ambiguity is the responsibility of the state 
table designer. If TPA$V_ABBRFM or TPA$V_ABBREV is set, 
LIB$T[ABLE_]PARSE ignores this value. 

A longword containing the number of characters remaining in 
the input string. 

A longword containing the address of the remainder of the 
string being parsed. Taken together, TPA$L_STRINGPTR and 
TPA$L_STRINGCNT form a descriptor for the input string. 

Your program initializes this descriptor with the string to be 
parsed. When LIB$TPARSE/LIB$TABLE_PARSE calls an action 
routine, this descriptor describes the remainder of the input 
string. When LIB$T[ABLE_JPARSE returns, this descriptor 
describes the portion of the input string that LIB$T[ABLE_ 
JPARSE did not process. (This occurs whether LIB$TPARSE 
/LIB$TABLE_PARSE returns success or failure.) 

A longword containing the number of characters in the current 
token. 

A longword containing the address of the current token. Taken 
together, TPA$L_TOKENPTR and TPA$L_TOKENCNT form 
a descriptor for the current token. If LIB$T[ABLE_]PARSE 
encounters a syntax error (fails to match a transition), then this 
descriptor describes whatever portion of the current input string 
would have been matched by a TPA$_SYMBOL symbol type. 

If none would have matched, it describes the first remaining 
character in the input string. A transition to TPA$_FAIL 
leaves the descriptor describing the token matched by that 
transition—that is, the string that failed. 

A byte containing the character matched by a single-character 
symbol type (V, TPA$_ANY, TPA$_ALPHA, or TPA$_DIGIT). 
The remainder of the longword is not used. 

(continued on next page) 
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Table LIB-8 (Cont.) Argument Block Fields 


Symbol 

Meaning 

TPA$L_NUMBER 

A longword containing the binary value of a numeric token 
(TPA$_DECIMAL, TPA$_OCTAL, or TPA$_HEX), converted in 
the appropriate radix. 

TPA$L_PARAM 

A longword containing the 32-bit argument supplied by the state 
transition. 


LIB$T[ABLE_]PARSE modifies the three preceding fields 
(TPA$L_CHAR, TPA$L_NUMBER, and TPA$L_PARAM) only 
when it is about to call an action routine from a transition of 
the relevant type (or containing an explicit argument). While 
LIB$T[ABLE_]PARSE is executing transitions of unrelated 
types, it does not modify the fields. 

TPA$K_LEN GTHO 

This symbol represents the number of bytes in the basic 
LIB$T[ABLE_]PARSE argument block. You must pass an 
argument block of at least this length (containing a count field 
of TPA$K_COUNTO in TPA$L_COUNT) as the first argument to 
LIB$TPARSE/LIB$TABLE_PARSE. You may pass a longer block 
if you wish to pass extra context to action routines in a modular 


way. 


The names TPA$M_BLANKS, TPA$M_ABBRFM, TPA$M_ABBREV, and TPA$M_ 
AMBIG define bitmasks that correspond to the location of the corresponding $V_ 
fields in the options longword. 

The State Tables This section describes the set of macros used to construct state 
tables. The section entitled “Coding and Using a Simple State Table” explains 
how to use these macros to construct a state table. 

The state table must be set up using either MACRO or BLISS. Everything else, 
including the action routines, can be coded in the language of your choice. Simply 
compile the state table separately, then link it with your program. 

MACRO State Table Generation Macro Calls The OpenVMS system macro 
library contains a set of assembler macros that allow convenient and readable 
coding of a LIB$T[ABLE_]PARSE state table. Macros exist to initialize the 
LIB$T[ABLE_]PARSE macro system, define the states in the state table, and 
define the transitions to other states within each state. These macros generate 
symbol definitions and tables. They do not produce any executable code or routine 
calls. 

$INIT_STATE—Initialize the LIB$T[ABLE_]PARSE Macros The $INIT_STATE 
macro declares the beginning of a state table. It initializes the internals of the 
table generator macros and declares the locations of the state table and the 
keyword table. The state table is the structure containing the definitions of the 
states and the transitions between them. The keyword table contains the text of 
the keywords used in the state table. 

$INIT_STATE state-table ,key-table 
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state-table 

The name assigned to the state table. LIB$T[ABLE_]PARSE equates this label to 
the start of the first state in the state table. 

key-table 

The name assigned to the keyword table. LIB$T[ABLE_]PARSE equates this 
label to the start of the keyword table. 

You must supply both the address of the state table and the address of the 
keyword table in the call to LIB$T[ABLE_]PARSE to perform a parse. The 
$INIT_STATE macro can appear more than once in a program. Each occurrence 
defines a separate state table. No part of any state table can refer to part of any 
other state table. 

$STATE—Defining a State The $STATE macro declares the beginning of a state. 
$STATE [label] 

label 

An optional label for the state. LIB$T[ABLE_]PARSE equates the label, if 
present, to the starting address of the state. 

$TRAN—Defining State Transitions The $TRAN macro defines a transition 
from the state in which it appears to some other (or to the same) state. The 
arguments of the macro define, among other things, the symbol type that causes 
the transition to be executed, the state to which to transfer, and the action routine 
to call, if any. 

$TRAN type [,label] [,action] [.mask] [,msk-adr] [.argument] 

type 

The symbol type recognized by this transition. The transition is taken if the 
characters at the front of the input string match the symbol specified. The symbol 
can be any of the constructs discussed in the section entitled “The Alphabet of 
LIB$TPARSE/LIB$TABLE_PARSE.” 

A subexpression symbol type has the syntax label. 

label 

The optional target state of this transition. If present, it must be the label 
assigned to some state in the state table. If no label is present in the transition, 
LIB$T[ABLE_]PARSE transfers control to the next state immediately following in 
the state table. If the label is the expression TPA$_EXIT, the parsing operation 
in progress is terminated with a success status. If the label is the expression 
TPA$_FAIL, the parsing operation stops with a failure status, as if a syntax error 
had occurred. 

action 

The optional address of a user-supplied action routine. If this argument is 
present, LIB$T[ABLE_]PARSE calls the named action routine before the 
transition is taken. The section entitled “Action Routines” describes the calling 
sequence of action routines and the information available to them. 

Since the action routine address is self-relative, it cannot be in a shared image 
separate from the state table. 
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mask 

An optional 32-bit mask value used with the msk-adr argument. If the mask 
is present, LIB$T[ABLE_]PARSE performs an inclusive OR operation using this 
value and the longword specified by msk-adr. Use of the mask argument allows 
the state table to flag the fact that a certain transition was taken without the 
expense and overhead of calling an action routine. 

msk-adr 

The optional address associated with the preceding mask argument. 
LIB$T[ABLE_]PARSE performs the inclusive OR operation on this address and 
the mask argument, and stores the result at the address. If the mask argument 
is present, the msk-adr argument must also be present. 

The msk-adr argument can also be present without the preceding mask 
argument. In this case, it specifies an address where the routine stores 
information about the matching token. The information stored depends on the 
nature of the symbol, as follows: 

• If the symbol is a number (that is, if the type code in the transition is TPA$_ 
DECIMAL, TPA$_OCTAL, or TPA$_HEX), the address contains the 32-bit 
binary value of the number (an unsigned longword). 

• If the symbol is a single character (that is, if the type code in the transition 
is 'x', TPA$_ANY, TPA$_ALPHA, or TPA$_DIGIT), the address (an unsigned 
byte) contains the 8-bit matching character. 

• If the symbol is of any other type, the address contains the 64-bit string 
descriptor of the matching token (an unsigned quadword; class and data type 
fields in the descriptor are undefined). 

Using msk-adr makes your program nonmodular. 

The use of the msk-adr alone lets a parser program extract the most commonly 
needed information from the input string without using action routines. Note 
that LIB$T[ABLE_]PARSE stores the information, and does not perform an OR 
operation as it does if mask is present. 

Since the action routine address is self-relative, it cannot be in a shared image 
separate from the state table. 

argument 

An optional 32-bit value that LIB$T[ABLE_]PARSE passes to the action routine 
without interpretation. This argument can be an identifier number, an address, 
or any other information your action routine needs. It allows a single action 
routine to serve many transitions for which similar, but slightly varying, actions 
must be performed. 

Using argument as an address is nonmodular. 

Note that the argument appears in the state table in its absolute form. Normally, 
LIB$T[ABLE_]PARSE stores addresses as self-relative pointers; however, 
LIB$T[ABLE_]PARSE does not know the form or meaning of argument, so it 
is stored in its absolute form. If argument is used as an address, therefore, 
the resulting parsing program containing this state table will not be position- 
independent code (PIC). 
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$END_STATE—End the State Table The $END_STATE macro declares the 
end of the state table. It is mandatory, in order to permit the orderly cleanup 
of the LIB$T[ABLE_]PARSE macro system. The $END_STATE macro has no 
arguments. You code it as follows: 

$END_STATE 

BLISS State Table Generation Macro Calls The file 
SYS$LIBRARY:TPAMAC.L32 contains a set of BLISS macros that allow 
convenient and readable coding of LIB$T[ABLE_]PARSE state tables in BLISS. 
To make the macros available to the program, include the following declaration in 
the module containing the state tables: 

LIBRARY ' SYS$LIBRARY:TPAMAC'; 

BLISS requires only two macros: $INIT_STATE to initialize the macros and 
$STATE to define each state in its entirety. The syntax of the $INIT_STATE and 
$STATE macros are defined below. 

$INIT_STATE—Initialize the LIB$T[ABLE_]PARSE Macros The $INIT_STATE 
macro initializes the LIB$T[ABLE_JPARSE macro system in the same manner as 
it does for the assembler. 

$INIT_STATE (state-table, key-table); 

state-table 

The name assigned to the state table. LIB$T[ABLE_]PARSE equates this label to 
the start of the first state in the state table. 

key-table 

The name assigned to the keyword table. LIB$T[ABLE_]PARSE equates this 
label to the start of the keyword table. 

Both names are declared as global vectors of length zero. As with the assembler 
macros, you can invoke $INIT_STATE more than once to declare several state 
tables within a single module. 

$STATE—Declaring a state and its transitions In BLISS, you use the $STATE 
macro to declare a state in its entirety. 

$STATE ([label], (transition ), (transition ), (transition )...); 

label 

Optional address of the start of the state. The compiler declares label as a 
local vector of length zero. Note that the comma following the optional label is 
mandatory. 

transition 

Each transition appears within the parentheses in the same form as the 
transition argument list for the assembler $TRAN macro. 

type [,label] [.action] [,mask] [,msk-adr] [.argument] 

The arguments of each transition are expressed in exactly the same format as in 
the assembler macros, with the exception of the subexpression type. In BLISS, 
this type has the form (label). 

Note that the transitions are not keyword macros. Therefore, you must use 
commas to indicate arguments you have skipped. 
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The BLISS table generation macros contain no BEGIN or END statements. This 
allows $STATE macros to refer to each other. They generate all storage with 
OWN declarations. This means that the macros modify PSECT declarations 
for OWN and GLOBAL storage. Thus if other data declarations follow the 
state table declarations, they may not have the correct attributes. You cannot 
simply surround the state table with BEGIN/END, because this constitutes an 
expression. No declarations of any kind, including ROUTINE declarations, can 
follow an expression. 

There are four techniques for including LIB$T[ABLE_]PARSE state tables in 
BLISS modules. 

1. Follow the state table with explicit redeclarations of the OWN and GLOBAL 
PSECTs. The BLISS example in the "Examples” section uses this technique. 

2. Place the state table in a separate module. The high-level language examples 
in the next section use this technique. 

3. Place the state table between BEGIN and END statements after the 
declarations within a routine body. 

4. Place the state table between BEGIN and END statements at the end of a 
module. 

In all cases, of course, you must define all action routines, masks, addresses, and 
arguments with suitable declarations (which can be FORWARD or EXTERNAL). 
The LIB$T[ABLE_]PARSE macros handle the necessary FORWARD declarations 
for forward references to labels within the state table. 

Coding and Using a Simple State Table 

LIB$T[ABLE_]PARSE can be used to parse programming languages, command 
languages, or any other grammar for which a deterministic parser is the best 
choice. The following sections show how to use it to parse the command language 
of a simple report management utility. 

This hypothetical utility allows a user to perform the following activities: 

1. Obtain a list of available reports (SHOW command). 

2. Read reports on the terminal (READ command). 

3. Print reports (PRINT command). 

4. Store new reports (FILE command). 

The examples use the BASIC programming language for everything except the 
state and keyword tables, which are coded in BLISS. 

Coding a parser program using LIB$T[ABLE_]PARSE involves three steps: 

1. Set up state tables to implement your language’s grammar. 

2. Define the argument block and other common variables. 

3. Code the main program, including the call to LIB$TPARSE/LIB$TABLE_ 
PARSE. 

This simple state table program does not use any action routines or other 
arguments. See the section entitled “Using Advanced LIB$T[ABLE_]PARSE 
Features” for information about how to use these features of LIB$TPARSE 
/LIB$TABLE_PARSE. 
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Setting up the State Tables A state table associates the parser’s alphabet with a 
set of possible transitions. You begin the state table with an $INIT_STATE macro 
and define the states and transitions using the $STATE and $TRAN macros. 

One easy way to set up these tables is to start from a transition diagram of the 
language you want to parse. (If you do not know how to construct a transition 
diagram, you might find it helpful to read a good introductory text about compiler 
design and construction before you start.) Each circle in the diagram becomes 
a $STATE macro, and each arrow representing a transition out of that state 
becomes a $TRAN macro. 

Figure LIB—23 shows a transition diagram for the mythical utility described in 
“Setting up the State Tables”. 

Figure LIB-23 Transition Diagram for the Mythical Utility 


Report Name 
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The state table for this simple language looks like this: 

.TITLE simplelang 
.ident 'vl' 


; + 

; Define the TPARSE control symbols 
$TPADEF 

$INIT_STATE SIMPLE_LANGUAGE_TABLE, SIMPLE_KEYWORD_TABLE 
$STATE START 

$TRAN 'PRINT', NEED_REPORT 
$TRAN 'READ', NEED_REPORT 
$TRAN 'FILE', NEED_REPORT 
$TRAN 'SHOW', NEED_REPORT 

$STATE NEED_REPORT 

$TRAN TPA$_SYMBOL, NEED_REPORT 

$TRAN TPA$_EOS, TPA$_EXIT 

$END_STATE 

.END 

Another technique for developing a state table starts with a tabular diagram 
in which the first column is the starting state, the second column identifies the 
input token, and the third gives the resultant state. 

Figure LIB—24 is a diagram of the same mythical utility that appeared in 
Figure LIB-23. 
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Figure LIB-24 Diagram of the Mythical Utility 
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In this case, each block of entries becomes a $STATE macro and each option 
within that block is a possible transition to the next state. Using the BLISS 
macros yields the following state table definition: 

MODULE simple_statetable = 

BEGIN 
! + 

! These libraries contain the macros and other definitions 
I needed to generate the state tables. 

i _ 

LIBRARY 'SYS$LIBRARY:STARLET'; 

LIBRARY 'SYS$LIBRARY:TPAMAC'; 

! + 

! UFD_STATE is the name you are giving the state table. 

! UFD_KEY names the keyword table. 

! Be sure to use the same name in the call to LIB$TPARSE/LIB$TABLE_PARSE. 

i _ 

$INIT_STATE (UFD_STATE, UFD_KEY); 

! + 

! Read the command name (to the first blank in the command). 

! Each string is a keyword; you are limited to 220 keywords 
! per state table. 

$STATE (START, !Be careful of your punctuation here. 

('CREATE'), ! Each transition is surrounded by 
('FILE'), ! parentheses; each entry except the 

I last is followed by a comma. 

('PRINT'), 

('READ') 

); 

$STATE (LOOP, 

(TPA$_STRING, LOOP), ! If there is more than one report name 
! specified, go back and process it. 

(TPA$_EOS, TPA$_EXIT) ! exit when done. 

)? 

END 

ELUDOM ! End of module CREATE_TABLE 

Assemble or compile this module as you would any other program module. 
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Defining the Argument Block After you have set up the state tables, you need 
to declare the LIB$TPARSE/LIB$TABLE_PARSE argument block in such a way 
that both your program and LIB$T[ABLE_]PARSE can use it. This means the 
data must be defined in an area common to the calling program and the program 
module containing the state table definitions. 

In most programming languages you will use a combination of EXTERNAL 
statements and common data definitions to create and access a separate data 
PSECT. If you do not know what mechanisms the language you are using 
provides, consult the documentation for that language. 

The following example shows the LIB$T[ABLE_]PARSE argument block defined 
for use in a BASIC program. 

!LIB$T[ABLE_]PARSE requires that TPA$K_COUNTO be eight. 

DECLARE INTEGER CONSTANT TPA$K_COUNTO =8, & 


BTPA$L_COUNT =0, & 
BTPA$L_0PTI0NS=1, & 
BTPA$L_STRINGCNT=2, & 
BTPA$L_STRINGPTR=3, & 
BTPA$L_TOKENCNT=4, & 
BTPA$L_TOKENPTR=5, & 
BTPA$B_CHAR=6, & 
BTPA$L_NUMBER=7, & 
BTPA$L_PARAM=8 

+ 


! The LIB$T[ABLE_]PARSE argument block. 

i _ 

MAP (TPARSE_BLOCK) LONG TPARSE_ARRAY (TPA$K_COUNTO) 

! + 

! Redefining the map allows you to use the standard 
! LIB$T[ABLE_]PARSE symbolic names. TPA$L_STRINGCNT, 

! for example, references the same storage location 
! as TPARSE_ARRAY(2) and TPARSE_ARRAY(BTPA$L_STRINGCNT). 


MAP (TPARSE_BLOCK) LONG & 

TPA$L_COUNT , & 

TPA$L_OPTIONS, & 

TPA$L_STRINGCNT, & 

TPA$L_STRINGPTR, & 

TPA$L_TOKENCNT, & 

TPA$L_TOKENPTR, & 

TPA$B_CHAR, & 

TPA$L_NUMBER, & 

TPA$L_PARAM 


Coding the Call to LIB$TPARSE/LIB$TABLE_PARSE Before your program can 
call LIB$TPARSE/LIB$TABLE_PARSE, it must place the necessary information 
in the argument block. Since this utility uses all the LIB$T[ABLE_]PARSE 
defaults for blanks processing, abbreviations, and so on, it does not need to set 
any flags. It must, however, put the address and length of the string to be parsed 
into the TPA$L_STRINGCNT and TPA$L_STRINGPTR fields. 

This information is available in the descriptor of the input string (called 
COMMAND_LINE in this program). However, BASIC, like most high-level 
languages, does not allow you to look at the descriptors of your strings. Instead, 
you can use LIB$ANALYZE_SDESC to read the length and address from the 
string descriptor and place them in the argument block. (See line 75.) 
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Note that this program uses the BLISS state table described in the section 
entitled “Setting Up the State Tables.” 

5 %TITLE "Program to demonstrate using LIB$T[ABLE_]PARSE from a high-level language 

OPTION TYPE=EXPLICIT 
! + 

! COMMAND_LINE is the string to receive the input 
! command from the terminal. 

! ERROR_MSG_TEXT is the system error message 
! returned from LIB$SYS_GETMSG 
! (used in the error handling routine) 

DECLARE STRING COMMAND_LINE, ERROR_MSG_TEXT 
! + 

! RET_STATUS receives the status from the system calls. 

! SAVE_STATUS is used when an error occurs 
! and the error handling routine calls 
! LIB$SYS_GETMSG to obtain the error text. 

DECLARE LONG RET_STATUS, SAVE_STATUS 
I + 

! UFD_STATE is the address of the state table. 

! UFD_KEY is the address of the key table. 

! Both addresses are set up by the macros in module 
! SIMPLE STATETABLE32. 


EXTERNAL LONG UFD_STATE, UFD_KEY 
! + 

! To allow us to compare returned statuses more easily. 

i _ 

EXTERNAL INTEGER CONSTANT SS$_NORMAL, & 

LIB$_SYNTAXERR, & 

LIB$_INVTYPE 

1 + 

! This program calls the following Run-Time Library 
! routines: 

i 

i LIB$T[ABLE_]PARSE to parse the input string 

i 

! LIB$ANALYZE_SDESC to get the length and starting 
! address of the command string and place them 
! in the LIB$T[ABLE_]PARSE argument block. 

i 

! LIB$SYS_GETMSG to find the facility, severity, and text 
i of any system errors that occur 

! during program execution. 


20 


EXTERNAL LONG FUNCTION LIB$TPARSE/LIB$TABLE_PARSE, & 

LIB$ANALYZE_SDESC, & 

LIB$SYS_GETMSG 

! + 

J This file defines the argument block that is passed 
! to LIB$TPARSE/LIB$TABLE_PARSE. It also defines subscripts that 
! make it easier to access the array. 

i 

! Keeping the argument block definitions in a separate 
! file makes them easier to modify and lets other 
! programs use the same definitions. 
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%INCLUDE "SIMPLE_TPARSE_BLOCK" 
50 ON ERROR GOTO ERROR HANDLER 


60 


LIB$T[ABLE_]PARSE requires that TPA$L_COUNT, the 
first field in the argument block, have a value 
of TPA$K_COUNTO, whose value is 8. 


TPA$L_COUNT = TPA$K_COUNTO 


75 ! + 

! Prompt at the terminal for the user's action. 

! A real utility should provide a friendlier, 
l clearer interface. 

i _ 

GET_INPUT: PRINT "Your options are: " , " READ report " 

PRINT , " FILE report " 

PRINT , " PRINT report " 

PRINT , " CREATE report " 

PRINT 

INPUT "What would you like to do"; COMMAND_LINE 

! + 

! Get the length and starting address of the command line 
1 and place them in the LIB$T[ABLE_]PARSE argument block. Note 
i that LIB$ANALYZE_SDESC stores the length as a word. 

i _ 

RET_STATUS = LIB$ANALYZE_SDESC (COMMAND_LINE BY DESC, & 
TPARSE_ARRAY (BTPA$L_STRINGCNT) BY REF, & 

TPARSE_ARRAY (BTPA$L_STRINGPTR) BY REF) 

IF RET_STATUS <> SS$_NORMAL THEN 

GOTO ERROR_HANDLER 

END IF 


100 I + 

! Call LIB$T[ABLE_]PARSE to process the input string. 

i 

! Note that LIB$T[ABLE_]PARSE expects to receive its arguments 
! by reference, while BASIC's default for arrays and 
! strings is by descriptor. Therefore the BY REF 
! clauses are required. Without them, LIB $ TPARSE/LIB $ TABLE_PARSE 
! cannot find the input string 
! and the parse will always fail. 

i _ 

RET_STATUS = LIB$T[ABLEJPARSE (TPARSE_ARRAY () BY REF, & 
UFD_STATE BY REF, & 

UFD_KEY BY REF ) 

! + 

! This simple program provides no information except that 
! a valid command was entered. The next section discusses 
l techniques for gathering more information. 

i _ 

IF RET_STATUS = SS$_NORMAL 
1 + 

l For now, exit on success. 

i _ 

THEN PRINT "Parse successful" 

GOTO 9999 
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! + 

! If the parse failed, give the user a chance to try again. 

i _ 

ELSE IF RET_STATUS = LIB$_SYNTAXERR THEN 

PRINT "You did not enter a valid command." 
PRINT "Please try again." 

GOTO GET_INPUT 

I + 

! If a more serious error occured, inform the user 
! and exit. 

i _ 

ELSE 

Goto ERROR_HANDLER 

END IF 

END IF 

500 ERROR_HANDLER: SAVE_STATUS = RET_STATUS 

RET_STATUS = LIB$SYS_GETMSG (SAVE_STATUS,,ERROR_MSG_TEXT) 
PRINT "Something went wrong." 

PRINT ERL, ERROR_MSG_TEXT 
RESUME 9999 

9999 END 


Compile this program as you would any other BASIC program. 

When both the state tables and the main program have been compiled, link them 
together to form a single executable image, as follows: 

$ LINK SIMPLANG,SIMPLANG_STATETABLE 

Using Advanced LIB$T[ABLE_]PARSE Features 

The simple LIB$T[ABLE_]PARSE call in the previous program tells you that the 
command the user entered was valid, but nothing else—not even which command 
was entered. Most of the time your program will need more information than 
this. 

The following sections describe some of the more complicated techniques you can 
use to gather extra information for your program. 

Action Routines When the transition being matched specifies an action routine 
to be called, LIB$T[ABLE_]PARSE stores the optional argument longword, if it is 
present, in the argument block and calls the action routine. If the action routine 
returns failure, LIB$T[ABLE_]PARSE continues attempting to match successive 
transitions. If the action routine returns success, LIB$T[ABLE_JPARSE executes 
the transition as it would if there was no action routine present. It stores the 
mask or other value at the mask address, if specified, and passes control to 
the specified target state. If no target state is given, control passes to the next 
state following in the state table. In either case, LIB$T[ABLE_]PARSE does not 
evaluate the remaining transitions in the state. 

When a state transition specifies an action routine, LIB$T[ABLE_]PARSE calls 
the action routine when the transition is found to be able to execute successfully 
(that is, when its symbol type matches a leading portion of the input string). It 
calls the action routine before processing the mask or msk-adr arguments of the 
state transition. 
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LIB$TPARSE uses a non-standard linkage that establishes the address of the 
argument block as the routine’s actual argument pointer. Thus an action routine 
can reference fields in the argument block by their symbolic offsets relative to the 
AP (Argument Pointer) register. 

For example: 

ROUTINE TEST = 

BEGIN 

BUILTIN 

AP; 

BIND 

TPARSE_ARGUMENT_BLOCK = AP : REF BLOCK[ , BYTE ]; 

TPARSE_ARGUMENT_BLOCK[ TPA$V_ABBREV ] = 1 
END; ♦ 

LIB$TABLE_PARSE uses the standard calling mechanism, and passes the 
TPARSE argument block, by reference, as the only argument to the action 
routine. 

So, for OpenVMS AXP systems, action routines are written as: 

ROUTINE TEST( TPARSE_ARGUMENT_BLOCK : REF BLOCK[ , BYTE ] ) = 

BEGIN 

TPARSE_ARGUMENT_BLOCK[ TPA$V_ABBREV ] = 1 
END; ♦ 

The action routine returns a value to LIB$T[ABLE_]PARSE in RO that controls 
execution of the current state transition. If the action routine returns success 
(low bit set in RO) then LIB$T[ABLE_]PARSE proceeds with the execution of 
the state transition. If the action routine returns failure (low bit clear in RO), 
LIB$T[ABLE_]PARSE rejects the transition that was being processed and acts 
as if the symbol type of that transition had not matched. It proceeds to evaluate 
other transitions in that state for eligibility. 

If an action routine returns a nonzero failure status to LIB$T[ABLE_]PARSE and 
no subsequent transitions in that state match, LIB$T[ABLE_]PARSE will return 
the status of the action routine, rather than the status LIB$_SYNTAXERR. In 
longword-valued functions in high-level languages, this value is returned in RO. 

Allowing action routines to reject a state transition allows you to implement 
symbol types specific to particular applications. To recognize a specialized 
symbol type, code a state transition using a LIB$T[ABLE_]PARSE symbol type 
that describes a superset of the desired set of possible tokens. The associated 
action routine then performs the additional discrimination necessary and returns 
success or failure to LIB$TPARSE/LIB$TABLE_PARSE, which then accordingly 
executes or fails to execute the transition. 

A pure finite-state machine, for instance, has difficulty recognizing strings that 
are shorter than some maximum length, or accepting numeric values confined to 
some particular range. 
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Blanks in the Input String The default mode of operation in LIB$T[ABLE_ 
JPARSE is to treat blanks as invisible separators. That is, they can appear 
between any two tokens in the string being parsed without being called for by 
transitions in the state table. Since blanks are significant in some situations, 
LIB$T[ABLE_]PARSE processes blanks if you have set the bit TPA$V_BLANKS 
in the options longword of the argument block. The following input string shows 
the difference in operation: 

ABC DEF 

LIB$T[ABLE_]PARSE recognizes the string by the following sequences of state 
transitions, depending on the state of the blanks control flag. 

TPA$V_BLANKS set: 

$STATE 

$TRAN TPA$_STRING 
$STATE 

$TRAN TPA$_BLANK 
$STATE 

$TRAN TPA$_STRING 
TPA$V_BLANKS clear: 

$STATE 

$TRAN TPA$_STRING 
$STATE 

$TRAN TPA$_STRING 

Your action routines can set or clear TPA$V_BLANKS as LIB$T[ABLE_]PARSE 
enters or leaves sections of the state table in which blanks are significant. 
LIB$T[ABLE_]PARSE always checks the blanks control flag as it enters a state. 
If the flag is clear, it removes any space or tab characters present at the front of 
the input string before it proceeds to evaluate transitions. Note that when the 
TPA$V_BLANKS flag is clear, the TPA$_BLANK symbol type will never match. 
If TPA$V_BLANKS is set, you must explicitly process blanks. 

Special Characters in the Input String Not all members of the ASCII character 
set can be entered directly in the state table definitions. Examples include the 
single quotation mark and all control characters. 

In MACRO state tables, such characters can be specified as the symbol type 
with any assembler expression that is equivalent to the ASCII code of the 
desired character, not including the single quotes. For example, you could code a 
transition to match a backspace character as follows: 

BACKSPACE = 8 


$TRAN BACKSPACE, ... 

MACRO places extra restrictions on the use of a comma in arguments to macros; 
often they must be surrounded by one or more angle brackets. Using a symbolic 
name for the comma will avoid such difficulties. 

To build a transition matching such a single character in a BLISS state table, you 
can use the %CHAR lexical function as follows: 
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LITERAL BACKSPACE = 8; 


$STATE (label, 

(%CHAR (BACKSPACE), ... ) 

)? 

Abbreviating Keywords The default mode of LIB$T[ABLE_]PARSE is exact 
match. All keywords in the input string must exactly match their spelling, length 
and case in the state table. However, many languages (command languages in 
particular) allow you to abbreviate keywords. For this reason, LIB$T[ABLE_ 
]PARSE has three abbreviation facilities to permit the recognition of abbreviated 
keywords when the state table lists only the full spellings. 

• By setting a value in TPA$B_MCOUNT in the LIB$T[ABLE_]PARSE 
argument block, the calling program or action routine specifies a minimum 
number of characters from the abbreviated keyword that must be present for 
a match to occur. For example, setting the byte to the value 4 would allow the 
keyword DEASSIGN to appear in an input string as DEAS, DEASS, DEASSI, 
DEASSIG, or DEASSIGN. 

LIB$T[ABLE_]PARSE checks all the characters of the keyword string. 
Incorrect spellings beyond the minimum abbreviation are not permitted. 

• If TPA$V_ABBRFM is set in the options longword, LIB$T[ABLE_]PARSE will 
recognize any leftmost substring of a keyword as a match for that keyword. 
LIB$TPARSE/LIB$TABLE_PARSE does not check for ambiguity; it matches 
the first keyword listed in the state table of which the input token is a subset. 

• If TPA$V_ABBREV is set in the options longword, LIB$T[ABLE_]PARSE 
will recognize any abbreviation of a keyword as long as it is unambiguous 
among the keywords in that state. If LIB$T[ABLE_]PARSE finds that the 
front of the input string contains an ambiguous keyword string, it sets the bit 
TPA$V_AMBIG in the options longword and refuses to recognize any keyword 
transitions in that state. (It still accepts other symbol types.) The TPA$V_ 
AMBIG flag can be checked by an action routine that is called when coming 
out of that state, or by the calling program if LIB$T[ABLE_]PARSE returns 
with a syntax error status. LIB$T[ABLE_]PARSE clears the flag when it 
enters the next state. 

For proper recognition of ambiguous keywords, the keywords in each state must 
be arranged in alphabetical order by the ASCII collating sequence, which is as 
follows: 

1. Dollar sign ($) 

2. Numerics 

3. Uppercase alphabetics 

4. Underscore (_) 

5. Lowercase alphabetics 

Be careful when using these options, since permitting short abbreviations 
restricts the extensibility of a language. Often, adding a new keyword can make 
a formerly valid abbreviation ambiguous. 

If both TPA$V_ABBRFM and TPA$V_ABBREV are set, TPA$V_ABBRFM takes 
precedence. 
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Using Subexpressions LIB$T[ABLE_]PARSE subexpressions are analogous 
to subroutines within the state table. A subexpression call, indicated with the 
MACRO expression Ilabel or the BLISS expression (label), causes LIB$T[ABLE_ 
]PARSE to call itself recursively, using the same argument block and keyword 
table, and the specified label as a starting state. LIB$TPARSE/LIB$TABLE_ 
PARSE processes the state transitions, consuming the portion of the input string 
called for. When LIB$T[ABLE_]PARSE executes a transition to TPA$_EXIT, it 
returns success to itself. LIB$T[ABLE_]PARSE thus considers the subexpression 
call a match, calls the action routine, and executes the transition. If the parse 
of the subexpression fails, LIB$T[ABLE_]PARSE returns the portion that it 
consumed during the failed parse to the input string, and evaluates the remaining 
transitions in the state. 

You can use subexpressions as you would use subroutines in any program: to 
avoid replication of complex expressions. Subexpressions can also be used for a 
limited form of pushdown parsing, in which the state table contains recursively 
nested subexpressions. Finally, you can use subexpressions for nondeterministic 
parsing, that is, parsing in which you need some number of states of look-ahead. 
To do this, place each path of look-ahead in a separate subexpression and call the 
subexpressions in the transitions of the state that needs the look-ahead. When a 
look-ahead path fails, the subexpression failure mechanism causes LIB$T[ABLE_ 
JPARSE to back out and try another path. 

You should be careful when designing subexpressions that contain calls to action 
routines or use the mask and msk-adr transition arguments. As LIB$T[ABLE_ 
JPARSE processes state transitions of a subexpression, it calls the specified 
action routines and stores the mask and msk-adr. If the subexpression fails, 
LIB$T[ABLE_]PARSE will back up the input string and resume processing in 
the calling state. However, any effects that the action routines have had on 
the caller’s data base cannot be undone. If subexpressions are simply being 
used as state table subroutines, there is usually no harm done, since when a 
subexpression fails in this mode, the parse will generally fail. This is not true 
of pushdown or nondeterministic parsing. In applications where you expect 
subexpressions to fail, design action routines to store results in temporary 
storage. You can then make these results permanent at the main level, where the 
flow of control is deterministic. 

Using Subexpressions to Reject Transitions The following example is an 
excerpt of a state table that parses a string quoted by an arbitrary character. 

The table interprets the first character to appear as a quote character. Many 
text editors and some programming languages contain this sort of construction. 
Executing this set of state transitions leaves a descriptor for the string in the two 
longwords at Q_DESCRIPTOR, and the quoting character at location Q_CHAR. 
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Main level state table. The first transition accepts and 
stores the quoting character. 

$STATE STRING 

$TRAN TPA$_ANY, , , ,Q_CHAR 

Call the subexpression to accept the quoted string and store 
the string descriptor. Note that the descriptor spans all 
the characters accepted by the subexpression. 

$STATE 

$TRAN !Q_STRING,,,,Q_DESCRIPTOR 

Accept the trailing quote character, left behind by the 
subexpression 

$STATE 

$TRAN TPA$_ANY,NEXT 

Subexpression to scan the quoted string. The first transition 
matches until it is rejected by the action routine. 

$STATE Q_STRING 

$TRAN TPA$_ANY,Q_STRING,TEST_Q 

$TRAN TPA$_LAMBDA,TPA$_EXIT 

The following MACRO subroutine compares the current character 
with the quoting character and returns failure if it matches. 


TEST_Q: 

.WORD 

0 ; 

: null entry mask 


CMPB 

TPA$B CHAR(AP), Q CHAR 

; check the character 


BNEQ 

10$ i 

: note R0 is already 1 

10$: 

CLRL 

RET 

R0 ; 

; match - reject transition 


Using Subexpressions to Parse Complex Grammars The following example 
is an excerpt from a state table that shows how to use subexpressions to parse 
complex grammars. The state table accepts a number followed by a keyword 
qualifier. Depending on the keyword, the table interprets the number as decimal, 
octal, or hexadecimal. The state table will accept strings such as the following: 

10/OCTAL 

32768/DECIMAL 

77AF/HEX 

This sort of grammar is difficult to parse with a deterministic finite-state 
machine. Using a subexpression look-ahead of two states permits a simpler 
expression of the state tables. 

; + 

; Main state table entry. Accept a number of some type and store 
; its value at the location NUMBER. 

$STATE 

$TRAN !OCT_NUM,NEXT,,,NUMBER 

$TRAN !DEC_NUM,NEXT,,,NUMBER 

$TRAN !HEX NUM,NEXT,,,NUMBER 
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; + 

; Subexpressions to accept an octal number followed by the OCTAL 
; qualifier. 

$STATE OCT_NUM 

$TRAN TPA$_OCTAL 

$STATE 

$TRAN '/' 

$STATE 

$TRAN 'OCTAL',TPA$_EXIT 

; + 

; Subexpression to accept a decimal number followed by the DECIMAL 
; qualifier. 

$STATE DEC_NUM 

$TRAN TPA$_DECIMAL 

$STATE 

$TRAN '/' 

$STATE 

$TRAN 'DECIMAL',TPA$_EXIT 

; + 

; Subexpression to accept a hex number followed by the HEX 
; qualifier. 

$STATE HEX_NUM 

$TRAN TPA$_HEX 

$STATE 

$TRAN '/' 

$STATE 

$TRAN 'HEX',TPA$_EXIT 

Note that the transitions following the numeric token do not disturb the TPA$_ 
NUMBER longword, allowing the main level subexpression call to retrieve it. 

LIB$T[ABLE_]PARSE and Modularity To use LIB$T[ABLEJPARSE in a modular 
and shareable fashion, make sure you avoid using OWN storage. Instead, allocate 
the argument block on the stack or the heap. 

Do not use the mask-adr argument at all. Do not use the argument argument 
as an address. 

If additional context is needed, allocate it at the end of the argument block. 

You will need to use action routines to control flags such as TPA$V_BLANKS. The 
MACRO example in the Examples section shows such an action routine, though 
the program itself is not modular. 

State Table Object Representation 

This section describes the binary representation of a LIB$T[ABLE_]PARSE state 
table. 

Each state consists of its transitions concatenated in memory. LIB$TPARSE 
/LIB$TABLE_PARSE equates the state label to the address of the first byte of 
the first transition. A marker in the last transition identifies the end of the state. 
The LIB$T[ABLE_]PARSE table macros build the state table in the PSECT _ 
LIB$STATE$. 

Each transition in a state consists of 2 to 23 bytes containing the arguments 
of the transition. The state table generation macros do not allocate storage for 
arguments not specified in the transition macro. This allows simple transitions 
to be represented efficiently. For example, the following transition, which simply 
accepts the character ' ?' and falls through to the next state, is represented in 
two bytes: 
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$TRAN '?' 

In this section, pointers described as self-relative are signed displacements 
from the address following the end of the pointer (this is identical to branch 
displacements in the OpenVMS instruction set). 

A state transition consists of the following elements: 

• Symbol Type—One Byte 

The first byte of a transition contains the binary coding of the symbol type 
accepted by this transition. It is always present. Flag bit 0 in the flags byte 
controls the interpretation of the type byte. If the flag is clear, then the type 
byte represents a single character (the 'x' construct). If the flag bit is set, 
then the type byte is one of the other type codes (keyword, number, and so 
forth). The symbol types accepted by LIB$T[ABLE_]PARSE are encoded in 
Table LIB-9. 


Table LIB-9 Symbol Types Accepted by LIB$TPARSE/LIB$TABLE_PARSE 


Symbol Type 

Binary Encoding 


ASCII code of the character (8 bits) 

' keyword' 

The keyword index (0 up to 219) 

TPA$_FILESPEC 

234 

TPA$_UIC 

235 

TPA$_IDENT 

236 

TPA$_ANY 

237 

TPA$_ALPHA 

238 

TPA$_DIGIT 

239 

TPA$_STRIN G 

240 

TPA$_SYMBOL 

241 

TPA$_BLANK 

242 

TPA$_DECIMAL 

243 

TPA$_OCTAL 

244 

TPA$_HEX 

245 

TPA$_LAMBDA 

246 

TPA$_EOS 

247 

TPA$_SUBEXPR 

248 (subexpression call) 

(Other codes are reserved for expansion) 


_ Note _ 

Use of the symbol types TPA$_FILESPEC and TPA$_IDENT will result 
in calls to the OpenVMS system services $FILESCAN and $ASCTOID, 
respectively. If your application of LIB$T[ABLE_]PARSE runs in an 
environment other than OpenVMS user mode, you must carefully evaluate 
whether use of these services is consistent with your environment. 


• First Flags Byte—One Byte 
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This byte contains the following bits, which specify the options of the 
transition. It is always present. 


Bit Description 

0 Set if the type byte is not a single character 

1 Set if the second flags byte is present 

2 Set if this is the last transition in the state 

3 Set if a subexpression pointer is present 

4 Set if an explicit target state is present 

5 Set if the mask longword is present 

6 Set if the msk-adr longword is present 

7 Set if an action routine address is present 


• Second Flags Byte—One Byte 

This byte is present if any of its flag bits is set. It contains an additional flag 
describing the transition. It is used as follows: 

Bit 0 Set if the action routine argument is present 

• Subexpression Pointer—Two Bytes 

This word is present in transitions that are subexpression calls. It is a 16-bit 
signed self-relative pointer to the starting state of the subexpression. 

• Argument Longword—Four Bytes 

This longword contains the 32-bit action routine argument, when specified. 

• Action Routine Address—Four Bytes 

This longword contains a self-relative pointer to the action routine, when 
specified. 

• Bit Mask—Four Bytes 

This longword contains the mask argument, when specified. 

• Mask Address—Four Bytes 

This longword, when specified, contains a self-relative pointer through which 
the mask, or data that depends on the symbol type, is to be stored. Because 
the pointer is self-relative, when it points to an absolute location, the state 
table is not PIC (position-independent code). 

• Transition Target—Two Bytes 

This word, when specified, contains the address of the target state of the 
transition. The address is stored as a 16-bit signed self-relative pointer. The 
final state TPA$_EXIT is coded as a word whose value is —1; the failure state 
TPA$_FAIL is coded as a word whose value is —2. 

• Keyword Table 

This table is the structure to which the $INIT_STATE macro equates its 
second argument. The table is a vector of 16-bit signed pointers which 
address locations in the keyword string area, relative to the start of 
the keyword vector. As the state table source generates keywords, the 
LIB$TPARSE/LIB$TABLE_PARSE macros assign an index number to 
each keyword. The index number is stored in the symbol type byte in the 
transition; it locates the associated keyword vector entry. The keyword 
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strings are stored in the order encountered in the state table. Each keyword 
string is terminated by a byte containing the value —1. Between the keywords 
of adjacent states is an additional —1 byte to stop the ambiguous keyword 
scan. 

To ensure that the keyword vector is adjacent to the keyword string area, the 
keyword vector is located in PSECT _LIB$KEYO$ and the keyword strings 
and stored in PSECT _LIB$KEY1$. 

Your program should not use any of the three PSECTs used by LIB$TPARSE 
/LIB$TABLE_PARSE (_LIB$STATE$, _LIB$KEY0$, and _LIB$KEY1$). The 
PSECTs _LIB$KEY0$ and _LIB$KEY1$ refer to each other using 16-bit 
displacements, so user PSECTs inserted between them can cause truncation 
errors from the linker. 


Condition Values Returned 

SS$_N ORMAL 

LIB$_SYNTAXERR 


LIB $_INVTYPE 
Other 


Routine successfully completed. LIB$T[ABLE_ 
]PARSE has executed a transition to TPA$_EXIT 
at main level, not within a subexpression. 

Parse completed with syntax error. 
LIB$T[ABLE_]PARSE has encountered a state 
at main level in which none of the transitions 
match the input string, or in which a transition 
to TPA$_FAIL was executed. 

State table error. LIB$T[ABLE_1PARSE has 
encountered an invalid entry in the state table. 

If an action routine returns a failure status 
other than zero, and the parse consequently 
fails, LIB$T[ABLE_]PARSE returns the status 
returned by the action routine. 


Examples 


1. 


/* 

** This DEC C program accepts and parses the command line of a CREATE/DIRECTORY 
** command. This program uses the LIB$GET_FOREIGN call to acquire the command 
** line from the CLI and parse it with LIB$TABLE_PARSE, leaving the necessary 
** information in its global data base. The command line is of 
** the following format: 

** 

** CREATE/DIR DEVICE:[MARANTZ.ACCOUNT.OLD] 

** /OWNER_UIC=[2437,25] 

** /ENTRIES=100 

* * /PROTECTION 3 (SYSTEM:R,OWNER:RWED,GROUP:R,WORLD:R) 

* * 

** The three qualifiers are optional. Alternatively, the command 
** may take the form: 

** 

** CREATE/DIR DEVICE:[202,31] 

** 

** using any of the optional qualifiers. 

** 

** The source for this program can be found in: 

** 

* * SYS$EXAMPLES:LIB$TABLE_PARSE_DEMO.COM 

** 

*/ 
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/* 

** Specify the required header files 
*/ 

# include "sys$library:tpadef" 

# include "sys$libraryrdescrip" 

# include "sys$library:starlet" 

# include "sys$library:lib$routines" 

/* 

** Specify macro definitions 
*/ 

# define max_name_count 8 

# define max_token_size 9 

# define uic_string_size 6 

# define command_buffer_size 256 

/* 

** Specify persistent data that's local to this module 
*/ 

static 

union 

uic_union { 

_int32 bits; 

struct { 
char first; 
char second; 

} bytes; 
struct { 

_inti6 first; 

_inti6 second; 

} words; 

} 

file_owner; /* Actual file owner UIC */ 

static 

int 

name_count; /* Number of directory names */ 

static 

char 

uic_string[ uic_string_size + 1 ]; /* Buffer for string */ 

static 

struct 

dsc$descriptor__s 

name_vector[ max_name_count ]; /* Vector of descriptors */ 

/* 

** Specify persistent data that's global to this module. 

** This data is referenced externally by the state table definitions. 

*/ 

union 

uic_union 

uTc_group, /* Temp for UIC group */ 

uic_member; /* Temp for UIC member */ 

int 

parser_flags, 
entry_count, 
file_protect; 

struct 

dsc$descriptor_s 

device_string = /* Device string descriptor */ 

{ 0, DSC$K_DTYPE_T, DSC$K_CLASS_S, (char *) 0 }; 


/* Keyword flags */ 

/* Space to preallocate */ 

/* Directory file protection */ 
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/* 

** Specify the user action routines. 

** 

** Please note that if it were LIB$TPARSE being called, the user action 
** routines would have to be coded as follows: 

** 

** int user_action_routine( _int32 psuedo_ap ) 

** { 

** struct tpadef 

** *tparse_block = (tpadef *) (&psuedo_ap - 1); 

** printf( "Parameter value: %d\n", 

** tparse_block->tpa$l_param 

** )? 

** y 

*/ 

/* 

** Shut off explicit blank processing after passing the command name. 

*/ 

int blanks_off( struct tpadef *tparse_block ) { 
tparse_block->tpa$v_blanks = 0; 
return( 1 ); 

} 

/* 

** Check the UIC for legal value range. 

*/ 

int check_uic( struct tpadef *tparse_block ) { 
if ( (uic_group.words.second != 0) | 

(uic_member.words.second != 0) 

) 

return( 0 ); 

file_owner.words.first = uic_member.words.first; 
file_owner.words.second = uic_group.words.first; 

return( 1 ); 

} 

/* 

** Store a directory name component. 

*/ 

int store_name( struct tpadef *tparse_block ) { 
if ( (name_count >= max_name_count) | 

(tparse_block->tpa$l_tokencnt > max_token_size) 

) 

return( 0 ); 

name_vector[ name_count ].dsc$w_length = tparse_block->tpa$l_tokencnt; 
name_vector[ name_count ].dsc$b_dtype = DSC$K_DTYPE_T; 
name_vector[ name_count ].dsc$b_class = DSC$K_CLASS_S; 

name_vector[ name_count++ ].dsc$a_pointer = tparse_block->tpa$l_tokenptr; 

return( 1 ); 

} 

/* 

** Convert a UIC into its equivalent directory file name. 

*/ 

int make_uic( struct tpadef *tparse_block ) { 

$DESCRIPTOR( control_string, "!OB!OB" ); 

$DESCRIPTOR( dirname, uic_string ); 
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if ( (uic_group.bytes.second ! = '\0') | 
(uic_member.bytes.second != '\0') 

) 

return( 0 ); 

sys$fao( &control_string, 

&dirname.dsc$w_length, 

&dirname, 

uic_group.bytes.first, 
uic_member.bytes.first 
)? 


return( 1 ); 

} 

/* 

** The main program section starts here. 

*/ 

main( ) { 

/* 

** This program creates a directory. It gets the command 
** line from the CLI and parses it with TPARSE. 

*/ 

extern 

char 

ufd_state, 

ufd_key; 

char 

command_buffer[ command_buffer_size + 1 ]; 
int 

status; 

$DESCRIPTOR( prompt, "Command> " ); 

$DESCRIPTOR( command_descriptor, command_buffer ); 

struct 

tpadef 

tparse_block = { TPA$K_COUNTO, /* Longword count */ 

TPA$M ABBREV /* Allow abbreviation */ 

T 

TPA$M_BLANKS /* Process spaces explicitly */ 

}; 

status = lib$get_foreign( &command_descriptor, 

&prompt, 

&command_descriptor.dsc$w_length 
)? 

if ( (status & 1) == 0 ) 
return( status ); 


/* 

** Copy the input string descriptor into the LIB$TABLE_PARSE control block 
** and then call LIB$TABLE_PARSE. Note that impure storage is assumed 
** to be zero. 

*/ 

tparse_block.tpa$l_stringcnt = command_descriptor.dsc$w_length; 
tparse_block.tpa$l_stringptr = command_descriptor.dsc$a_pointer; 

return( status = lib$table_parse( &tparse_block, &ufd_state, &ufd_key ) ); 

} 
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The preceding DEC C program accepts and parses the command line of a 
CREATE/DIRECTORY command. 


.TITLE CREATE_DIR_TABLES - Create Directory File (tables) 

.IDENT "X-l" 


This module defines the TPARSE state tables for preceding sample program 
(which accepts and parses the command line of the CREATE/DIRECTORY command). 
This program contains the OpenVMS call to acquire the command line from the 
command interpreter and parse it with TPARSE, leaving the necessary 
information in its global data base. The command line has the 
following format: 

CREATE/DIR DEVICE:[MARANTZ.ACCOUNT.OLD] 

/OWNER_UIC=[2437,25] 

/ENTRIES=100 

/PROTECTION(SYSTEM:R,OWNER:RWED,GROUP:R,WORLD:R) 

The three qualifiers are optional. Alternatively, the command 
may take the form 

CREATE/DIR DEVICE:[202,31] 

using any of the optional qualifiers. 


+ 

Global data, control blocks, etc. 


.PSECT IMPURE,WRT,NOEXE 

? + 

; Define control block offsets 


$CLIDEF 

$TPADEF 

.EXTRN BLANKS_OFF, - ; No explicit blank processing 

CHECKJJIC, - ; Validate and assemble UIC 

STORE_NAME, - ; Store next directory name 

MAKE_UIC ; Make UIC into directory name 


; + 

; Define parser flag bits for flags longword 

r ~ 

UIC_FLAG = 1 ; /UIC seen 

ENTRIES_FLAG = 2 ; /ENTRIES seen 

PROT_FLAG = 4 ; /PROTECTION seen 

.SBTTL Parser State Table 

? + 

; Assign values for protection flags to be used when parsing protection 
; string. 
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SYS TEM_READ_FLAG = A X0001 
S Y STEM_WRI TE_FLAG = A X0002 
SYSTEM_EXECUTE_FLAG = A X0004 
SYSTEM_DELETE_FLAG = A X0008 
GROUP_READ_FLAG = A X0001 
GROUP_WRITE_FLAG = A X0002 
GROUP_EXECUTE_FLAG = A X0004 
GROUP_DELETE_FLAG = A X0008 
OWNER_READ_FLAG = A X0001 
OWNER_WRITE_FLAG = A X0002 
OWNER_EXECUTE_FLAG = A X0004 
OWNER_DELETE_FLAG = A X0008 
WORLD_READ_FLAG = A X0001 
WORLD_WRITE_FLAG = A X0002 
WORLD_EXECUTE_FLAG = A X0004 
WORLD_DELETE_FLAG = A X0008 

$INIT_STATE UFD_STATE,UFD_KEY 

; + 

; Read over the command name (to the first blank in the command). 


$STATE START 

$TRAN TPA$_BLANK, ,BLANKS_OFF 

$TRAN TPA$ ANY,START 


Read device name string and trailing colon. 


$STATE 

$TRAN TPA$_SYMBOL,,,,DEVICE_STRING 

$STATE 

$TRAN ':' 

+ 

Read directory string, which is either a UIC string or a general 
directory string. 

$STATE 

$TRAN !UIC,,MAKE_UIC 

$TRAN INAME 


Scan for options until end of line is reached 


$STATE OPTIONS 

$TRAN '/' 

$TRAN TPA$_EOS,TPA$_EXIT 

$STATE 

$TRAN 'OWNERJJIC',PARSE_UIC,,UIC_FLAG,PARSER_FLAGS 

$TRAN 'ENTRIES',PARSE_ENTRIES,,ENTRIES_FLAG,PARSER_FLAGS 

$TRAN 'PROTECTION',PARSE PROT,,PROT FLAG,PARSER FLAGS 


Get file owner UIC. 


$ STATE PARSEJJIC 

$TRAN ':' 

$TRAN 

$STATE 

$TRAN !UIC,OPTIONS 
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Get number of directory entries. 


$STATE PARSE_ENTRIES 

$TRAN ':' 

$TRAN 

$STATE 

$TRAN TPA$_DECIMAL, OPTIONS, , , ENTRY_COUNT 

Get directory file protection. Note that the bit masks generate the 
protection in complement form. It will be uncomplemented by the main 
program. 

$STATE PARSE_PROT 

$TRAN ':' 


$TRAN 

t — ! 

$STATE 

$TRAN 


$STATE 

NEXT PRO 

$TRAN 

'SYSTEM' , SYPR 

$TRAN 

'OWNER ' , OWPR 

$TRAN 

'GROUP' , GRPR 

$TRAN 

'WORLD' , WOPR 

$STATE 

SYPR 

$TRAN 

/ • / 

$TRAN 

r = r 

$STATE 

SYPRO 

$TRAN 

'R',SYPRO,,SYSTEM READ FLAG,FILE PROTECT 

$TRAN 

'W' , SYPRO, , SYSTEM WRITE FLAG,FILE PROTECT 

$TRAN 

'E' , SYPRO, , SYSTEM EXECUTE FLAG,FILE PROTECT 

$TRAN 

'D' , SYPRO, , SYSTEM DELETE FLAG,FILE PROTECT 

$TRAN 

TPA$_LAMBDA,ENDPRO 

$STATE 

OWPR 

$TRAN 

/ « / 

$TRAN 

/ = f 

$STATE 

OWPRO 

$TRAN 

'R' , OWPRO ,, OWNER READ FLAG,FILE PROTECT 

$TRAN 

'W' , OWPRO, , OWNER WRITE FLAG,FILE PROTECT 

$TRAN 

'E' , OWPRO, , OWNER EXECUTE FLAG,FILE PROTECT 

$TRAN 

'D' , OWPRO, , OWNER DELETE FLAG,FILE PROTECT 

$TRAN 

TPA$_LAMBDA , ENDPRO 

$STATE 

GRPR 

$TRAN 

/ • t 

$TRAN 

r = i 

$STATE 

GRPRO 

$TRAN 

'R',GRPRO, , GROUP READ FLAG,FILE PROTECT 

$TRAN 

'W' , GRPRO, , GROUP WRITE FLAG,FILE PROTECT 

$TRAN 

'E' , GRPRO, , GROUP EXECUTE FLAG,FILE PROTECT 

$TRAN 

'D' , GRPRO, , GROUP DELETE FLAG,FILE PROTECT 

$TRAN 

TPA$_LAMBDA,ENDPRO 

$STATE 

WOPR 

$TRAN 

/ . ! 

$TRAN 

r — t 
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$STATE WOPRO 

$TRAN 'R',WOPRO,,WORLD_READ_FLAG,FILE_PROTECT 

$TRAN 'W',WOPRO,,WORLD_WRITE_FLAG,FILE_PROTECT 

$TRAN 'E',WOPRO,,WORLD_EXECUTE_FLAG,FILE_PROTECT 

$TRAN 'D',WOPRO,,WORLD_DELETE_FLAG,FILE_PROTECT 

$TRAN TPA$_LAMBDA,ENDPRO 

$STATE ENDPRO 

$TRAN <','>,NEXT_PRO 

$TRAN OPTIONS 


+ 

Subexpression to parse a UIC string. 


$STATE 

UIC 


$TRAN 



$STATE 

$TRAN 

TPA$_OCTAL,,, 

,UIC_GROUP 

$STATE 

$TRAN 

<V> 

; The comma character must be 
; surrounded by angle brackets 

; because MACRO restricts the use 

; of commas in arguments to macros 

$STATE 

$TRAN 

TPA$_OCTAL,,, 

,UIC_MEMBER 

$STATE 

$TRAN 

']',TPA$_EXIT 

,CHECK_UIC 

Subexpression to 

parse a general directory string 

$STATE 

NAME 


$TRAN 



$STATE 

NAMEO 


$TRAN 

TPA$_STRING,, 

STORE_NAME 

$STATE 

$TRAN 

'.',NAMEO 


$TRAN 

']',TPA$_EXIT 


$END STATE 




.END 


The preceding MACRO program module defines the TPARSE state tables for 
the preceding sample program which accepts and parses the command line of 
CREATE/DIRECTORY command. 
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MODULE CREATE_DIR ( i Create directory file 

IDENT = 'X0000', 

MAIN = CREATE_DIR) = 

BEGIN 
! + 

! This VAX BLISS program accepts and parses the command line 
! of a CREATE/DIRECTORY command. This program uses the 
i LIB$GET_FOREIGN call to acquire the command line from 
! the CLI and parse it with LIB$TPARSE, leaving the necessary 
i information in its global data base. The command line is of 
! the following format: 

i 

! CREATE/DIR DEVICE:[MARANTZ.ACCOUNT.OLD] 

! /UIC=[2437,25] 

! /ENTRIES=100 

! /PROTECTION=(SYSTEM:R,OWNER:RWED,GROUP:R,WORLD:R) 

i 

1 The three qualifiers are optional. Alternatively, the command 
! may take the form 

i 

! CREATE/DIR DEVICE:[202,31] 

i 

! using any of the optional qualifiers. 


! + 

! Global data, control blocks, etc. 

i _ 

LIBRARY 'SYS$LIBRARY:STARLET'; 

LIBRARY 'SYS$LIBRARY:TPAMAC.L32'; 

! + 

! Macro to make the TPARSE control block addressable as a block 
! through the argument pointer. 

i _ 

MACRO 

TPARSE_ARGS = 

BUILTIN AP; 

MAP AP : REF BLOCK [,BYTE]; 

%; 

! + 

! Declare routines in this module. 

i _ 

FORWARD ROUTINE 

CREATE_DIR, 

BLANKS_OFF, 

CHECKJJIC, 

STORE_NAME, 

MAKEJJIC; 

! + 

! Define parser flag bits for flags longword. 

i _ 

LITERAL 

UIC_FLAG =0, ! /UIC seen 

ENTRIES_FLAG =1, ! /ENTRIES seen 

PROTJFLAG =2; ! /PROTECTION seen 

OWN 
1 + 

! This is the LIB$GET_FOREIGN descriptor block to get the command line. 

i _ 

COMMAND_DESC : BLOCK [DSC$K_S_BLN, BYTE], 

COMMAND_BUFF : VECTOR [256, BYTE], 


! Mail program 

! No explicit blank processing 
! Validate and assemble UIC 
! Store next directory name 
! Make UIC into directory name 
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i + 

! This is the TPARSE argument block. 


TPARSE_BLOCK : BLOCK [TPA$K_LENGTHO, BYTE] 

INITIAL (TPA$K_COUNTO, ! Longword count 

TPA$M_ABBREV ! Allow abbreviation 

OR TPA$M_BLANKS), ! Process spaces explicitly 

! + 

! Parser global data: 


PARSER FLAGS : 

BITVECTOR [32], 

! Keyword flags 

DEVICE STRING : 

VECTOR [2], 

! Device string descriptor 

ENTRY COUNT, 


! Space to preallocate 

FILE PROTECT, 


l Directory file protection 

UIC GROUP, 


! Temp for UIC group 

UIC MEMBER, 


! Temp for UIC member 

FILE OWNER, 


! Actual file owner UIC 

NAME COUNT, 


! Number of directory names 

UIC_STRING : 

VECTOR [6, BYTE 

, ! Buffer for string 

NAME_VECTOR : 

BLOCKVECTOR [0, 

2], ! Vector of descriptors 

DIRNAME1 

VECTOR [2], 

! Name descriptor 1 

DIRNAME2 

VECTOR [2], 

! Name descriptor 2 

DIRNAME3 

VECTOR [2], 

! Name descriptor 3 

DIRNAME4 

VECTOR [2], 

! Name descriptor 4 

DIRNAME5 

VECTOR [2], 

! Name descriptor 5 

DIRNAME6 

VECTOR [2], 

! Name descriptor 6 

DIRNAME7 

VECTOR [2], 

! Name descriptor 7 

DIRNAME8 

VECTOR [2]; 

i Name descriptor 8 


i + 

! Structure macro to reference the descriptor fields in the vector of 
! descriptors. 

i _ 

MACRO 

STRING_COUNT = 0, 0, 32, 0%, ! Count field 

STRING_ADDR = 1, 0, 32, 0%; ! Address field 

! + 

! TPARSE state table to parse the command line 

i _ 

$INIT_STATE (UFD_STATE, UFD_KEY); 

! + 

! Read over the command name (to the first blank in the command). 


$STATE (START, 

(TPA$_BLANK, , BLANKS_OFF), 

(TPA$_ANY, START) 

); 

! + 

I Read device name string and trailing colon. 

i _ 

$STATE (, 

(TPA$_SYMBOL,,,, DEVICE_STRING) 

); 

$STATE (, 

); 
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Read directory string, which is either a UIC string or a general 
directory string. 


$STATE (, 

((UIC),, MAKEJJIC), 
((NAME)) 

); 


! + 

! Scan for options until end of line is reached. 


$STATE (OPTIONS, 

('/'), 

(TPA$_EOS, TPA$_EXIT) 

); 

$STATE (, 

('UIC', PARSE_UIC,, 1 A UIC_FLAG, PARSER_FLAGS), 

('ENTRIES', PARSE_ENTRIES,, 1 A ENTRIES_FLAG, PARSER_FLAGS), 
('PROTECTION', PARSE_PROT,, 1 A PR0T_FLAG, PARSER_FLAGS) 

); 

! + 

! Get file owner UIC. 

i _ 

$STATE (PARSE_UIC, 

('■'), 

(' = ') 

); 

$STATE (, 

((UIC), OPTIONS) 

); 

i + 

! Get number of directory entries. 

; _ 

$STATE (PARSE_ENTRIES, 

(':'), 

(' = ') 

); 

$STATE (, 

(TPA$_DECIMAL, OPTIONS,,, ENTRY_COUNT) 

); 

i+ 

! Get directory file protection. Note that the bit masks generate the 
! protection in complement form. It will be uncomplemented by the main 
! program. 

j _ 

$STATE (PARSE_PROT, 

('«')# 

(' = ') 

); 

$STATE (, 

('(') 

); 
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$STATE (NEXT_PRO, 

('SYSTEM', SYPR), 

('OWNER', OWPR), 

('GROUP', GRPR), 

('WORLD', WOPR) 

); 

$STATE (SYPR, 

('•■'), 

(' = ') 

); 

$STATE (SYPRO, 

('R', SYPRO,, %X'0001', FILE_PROTECT), 
('W', SYPRO,, %X'0002', FILE_PROTECT), 
('E', SYPRO,, %X'0004', FILE_PROTECT), 
('D', SYPRO,, %X'0008', FILE_PROTECT), 
(TPA$_LAMBDA, ENDPRO) 

); 

$STATE (OWPR, 

('■'), 

(' = ') 

\ • 


$STATE (OWPRO, 

('R', OWPRO,, %X'0010', FILE_PROTECT), 
('W', OWPRO,, %X'0020', FILE_PROTECT), 
('E', OWPRO,, %X'0040', FILE_PROTECT), 
('D', OWPRO,, %X'0080', FILE_PROTECT), 
(TPA$_LAMBDA, ENDPRO) 


$STATE (GRPR, 

(' = ') 

); 

$STATE (GRPRO, 

('R', GRPRO,, %X'0100', FILE_PROTECT), 
('W', GRPRO,, %X'0200', FILE_PROTECT), 
('E', GRPRO,, %X'0400', FILE_PROTECT), 
('D', GRPRO,, %X'0800', FILE_PROTECT), 
(TPA$_LAMBDA, ENDPRO) 

>; 

$STATE (WOPR, 

(' = ') 

); 

$STATE (WOPRO, 

('R', WOPRO,, %X'1000', FILE_PROTECT), 
('W', WOPRO,, %X'2000', FILE_PROTECT), 
('E', WOPRO,, %X'4000', FILE_PROTECT), 
('D', WOPRO,, %X'8000', FILE_PROTECT), 
(TPA$_LAMBDA, ENDPRO) 

); 

$STATE (ENDPRO, 

(', ', NEXT_PRO), 

(')', OPTIONS) 


Subexpression to parse a UIC string. 


$STATE (UIC, 
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('[') 

); 

$STATE 

( ! 


(TPA$ OCTAL,,,, UIC GROUP) 

); 

$STATE 

(, 


(\ ') 

); 

$STATE 

( ! 

(TPA$ OCTAL,,,, UIC MEMBER) 
); 

$STATE 

(, 

(']', TPA$_EXIT, CHECK_UIC) 


); 

! + 

! Subexpression to parse a general directory string 

i _ 

$STATE (NAME, 

('[') 

); 

$STATE (NAMEO, 

(TPA$_STRING,, STORE_NAME) 

); 

$STATE (, 

('.', NAMEO), 

TPA$_EXIT) 

); 

PSECT OWN = $OWN$; 

PSECT GLOBAL = $GLOBAL$; 

GLOBAL ROUTINE CREATE_DIR (START_ADDR, CLI_CALLBACK) = 

BEGIN 
! + 

! This program creates a directory. It gets the command 
! line from the CLI and parses it with TPARSE. 

i _ 

LOCAL 

STATUS, ! Status from LIB$TPARSE 

OUT_LEN : WORD; ! length of returned command line 

EXTERNAL 

SS$_NORMAL; 

EXTERNAL ROUTINE 

LIB$GET_FOREIGN : ADDRESSING_MODE (GENERAL), 

LIB$TPARSE : ADDRESSING_MODE (GENERAL); 

COMMAND_DESC [DSC$W_LENGTH] = 256; 

COMMAND_DESC [DSC$B_DTYPE] = DSC$K_DTYPE_T; 
COMMAND_DESC [DSC$B_CLASS] = DSC$K_CLASS_S; 
COMMAND_DESC [DSC$A_POINTER] = COMMAND_BUFF; 

STATUS = LIB$GET_FOREIGN (COMMAND_DESC, 

%ASCID'COMMAND: ', 

OUT_LEN 

); 

IF NOT .STATUS 
THEN 

SIGNAL (STATUS); 
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! + 

! Copy the input string descriptor into the TPARSE control block 
! and call TPARSE. Note that impure storage is assumed to be zero. 

i _ 

TPARSE_BLOCK[TPA$L_STRINGCNT] = .OUT_LEN; 

TPARSE_BLOCK[TPA$L_STRINGPTR] = .COMMAND_DESC[DSC$A_POINTER]; 

STATUS = LIB$TPARSE (TPARSE_BLOCK, UFD_STATE, UFD_KEY); 

IF NOT .STATUS 
THEN 

RETURN 0; 

RETURN SS$_NORMAL 

END; ! End of routine CREATE_DIR 

! + 

! Parser action routines 

j _ 

! + 

! Shut off explicit blank processing after passing the command name. 

i _ 

ROUTINE BLANKS_OFF = 

BEGIN 

TPARSE_ARGS; 

AP[TPA$V_BLANKS] = 0; 

1 

END; 


! Check the UIC for legal value range. 


ROUTINE CHECK JJIC = 

BEGIN 

TPARSE_ARGS; 

IF .UIC_GROUP<16,16> NEQ 0 
OR .UIC_MEMBER<16,16> NEQ 0 
THEN RETURN 0; 

FILE_OWNER<0 / 16> = .UIC__MEMBER; 
FILE_OWNER<16,16> = .UIC_GROUP; 
1 

END; 


! + 

! Store a directory name component. 

i _ 

ROUTINE STORE_NAME = 

BEGIN 

TPARSE_ARGS; 

IF .NAME_COUNT GEQU 8 

OR .AP[TPA$L_TOKENCNT] GTRU 9 

THEN RETURN 0; 

NAME_COUNT = .NAME_COUNT + 1; 

NAME_VECTOR [.NAME_COUNT, STRING_COUNT] = .AP[TPA$L_TOKENCNT]; 

NAME_VECTOR [.NAME_COUNT, STRING_ADDR] = .AP[TPA$L_TOKENPTR]; 

1 

END; 


! + 

i Convert a UIC into its equivalent directory file name. 
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ROUTINE MAKEJJIC = 

BEGIN 

TPARSE_ARGS; 

IF .UIC_GROUP<8,8> NEQ 0 
OR .UIC_MEMBER<8,8> NEQ 0 
THEN RETURN 0; 

DIRNAME1[0] = 0; 

DIRNAME1[1] = UIC_STRING; 

$FAOL (CTRSTR = UPLIT (6, UPLIT BYTE ('!OB!OB')), 

OUTBUF = DIRNAMEl, 

PRMLST = UIC_GROUP 

)? 

1 

END; 

END 

ELUDOM ! End of module CREATE_DIR 

The preceding VAX BLISS program accepts and parses the command line of a 
CREATE/DIRECTORY command. 


.TITLE CREATE_DIR - Create Directory File 

.IDENT "X0000" 

+ 

This is a sample VAX program that accepts and parses the command line 
of the CREATE/DIRECTORY command. This program contains the OpenVMS 
call to acquire the command line from the command interpreter 
and parse it with TPARSE, leaving the necessary information in 
its global data base. The command line has the following format: 

CREATE/DIR DEVICE:[MARANTZ.ACCOUNT.OLD] 

/OWNER__UIC=[ 2437, 25 ] 

/ENTRIES=100 

/PROTECTION=(SYSTEM:R,OWNER:RWED,GROUP:R,WORLD:R) 

The three qualifiers are optional. Alternatively, the command 
may take the form 

CREATE/DIR DEVICE:[202,31] 

using any of the optional qualifiers. 


+ 

Global data, control blocks, etc. 


.PSECT IMPURE,WRT,NOEXE 

Define control block offsets 

$CLIDEF 

$TPADEF 

Define parser flag bits for flags longword 


UIC_FLAG = 1 
ENTRIES_FLAG = 2 
PROT FLAG = 4 


/UIC seen 
/ENTRIES seen 
/PROTECTION seen 
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+ 

LIB$GET_FOREIGN string descriptors to get the line to be parsed 


STRING_LEN =256 
STRINGJDESC: 

.WORD STRINGJLEN 
.BYTE DSC$K_DTYPE_T 
.BYTE DSC$K_CLASS_S 
.ADDRESS STRING_AREA 
STRING_AREA: 

.BLKB STRING_LEN 
PROMPT_DESC: 

.WORD PROMPT_LEN 
.BYTE DSC$K_DTYPE_T 
.BYTE DSC$K_CLASS_S 
.ADDRESS PROMPT 


PROMPT: 

.ASCII /qualifiers: / 
PROMPT LEN = .-PROMPT 


+ 

TPARSE argument block 


TPARSE BLOCK: 


.LONG 


TPA$K COUNTO 


.LONG 


TPA$M ABBREV 

- 



TPA$M BLANKS 


.BLKB 

• _L 


TPA$K_LENGTH0-8 

; Parser global data 



RET LEN: 


.BLKW 

1 

PARSER FLAGS: 


.BLKL 

1 

DEVICE STRING: 


.BLKL 

2 

ENTRY COUNT: 


.BLKL 

1 

FILE PROTECT: 


.BLKL 

1 

UIC GROUP: 


.BLKL 

1 

UIC MEMBER: 


.BLKL 

1 

UIC STRING: 


.BLKB 

6 

FILE OWNER: 


.BLKL 

1 

NAME COUNT: 


.BLKL 

1 

DIRNAME1: 


.BLKL 

2 

DIRNAME2: 


.BLKL 

2 

DIRNAME3: 


.BLKL 

2 

DIRNAME4: 


.BLKL 

2 

DIRNAME5: 


.BLKL 

2 

DIRNAME6: 


.BLKL 

2 

DIRNAME7: 


.BLKL 

2 

DIRNAME8: 


.BLKL 

2 

.SBTTL 

. _L 

Main Program 


; This program gets the CREATE/DIRECTORY 

; the command interpreter and parses it. 

.PSECT 

CODE 

EXE,NOWRT 


CREATE DIR:: 




.WORD 

A M<R2,R3,R4,R5> 



Longword count 
Allow abbreviation 
Process spaces explicitly 
Remainder set at run time 


LENGTH OF RETURNED COMMAND LINE 

Keyword flags 

Device string descriptor 

Space to preallocate 

Directory file protection 

Temp for UIC group 

Temp for UIC member 

String to receive converted UIC 

Actual file owner UIC 

Number of directory names 

Name descriptor 1 

Name descriptor 2 

Name descriptor 3 

Name descriptor 4 

Name descriptor 5 

Name descriptor 6 

Name descriptor 7 

Name descriptor 8 


command line from 


; Save registers 
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Call the command interpreter to obtain the command line. 

PUSHAW RET_LEN 
PUSHAQ PROMPT_DESC 
PUSHAQ STRING_DESC 

CALLS #3,G A LIB$GET_F0REIGN ; Call to get command line 
BLBC RO, SYNTAX_ERR 


Copy the input string descriptor into the TPARSE control block 

and call LIB$TPARSE. Note that impure storage is assumed to be zero. 


MOVZWL 

RET LEN, TPARSE BLOCK+TPA$L STRINGCNT 

MOVAL 

STRING AREA, TPARSE BLOCK+TPA$L STRINGPTR 

PUSHAL 

UFD KEY 

PUSHAL 

UFD STATE 

PUSHAL 

TPARSE BLOCK 

CALLS 

#3,G*LIB$TPARSE 

BLBC 

RO,SYNTAX ERR 


Parsing is complete. 

You can include here code to process the string just parsed, to call 
another program to process the command, or to return control to 
a calling program, if any. 


SYNTAX_ERR: 

? + 

; Code to handle parsing errors. 


RET 

.SBTTL Parser State Table 

Assign values for protection flags to be used when parsing protection 
string. 


SYSTEM_READ_FLAG = A X0001 

SYSTEM_WRITE_FLAG = A X0002 
SYSTEM_EXECUTE_FLAG = A X0004 
SYS TEM_DELE TE_FLAG = A X0008 
GROUP_READ_FLAG = A X0001 
GROUP_WRITE_FLAG = A X0002 
GROUP_EXECUTE_FLAG = A X0004 
GROUP_DELETE_FLAG = A X0008 
OWNER_READ_FLAG = A X0001 
OWNER_WRITE_FLAG = A X0002 
OWNER_EXECUTE_FLAG = A X0004 
OWNER_DELETE_FLAG = A X0008 
WORLD_READ__FLAG = A X0001 
WORLD_WRITE_FLAG = A X0002 
WORLD_EXECUTE_FLAG = A X0004 
WORLD DELETE FLAG = A X0008 


$INIT_STATE UFD_STATE,UFD_KEY 
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+ 


; Read over the 

command name (to the first blank in the command). 

$STATE 

START 

$TRAN 

TPA$ BLANK,,BLANKS OFF 

$TRAN 

. _L 

TPA$ ANY,START 

f 1 

; Read device name string and trailing colon. 

$STATE 

$TRAN 

TPA$_SYMBOL,,,,DEVICE_STRING 

$STATE 

$TRAN 

> 4- 

/ • > 

1 ' 

Read directory string, which is either a UIC string or a general 

directory string. 

$STATE 

$TRAN 

!UIC,,MAKE UIC 

$TRAN 

INAME 

? + 

; Scan for options until end of line is reached 

$STATE 

OPTIONS 

$TRAN 

'/' 

$TRAN 

TPA$ EOS,TPA$ EXIT 

$STATE 

$TRAN 

'OWNER UIC',PARSE UIC,,UIC FLAG,PARSER FLAGS 

$TRAN 

'ENTRIES',PARSE ENTRIES,,ENTRIES FLAG,PARSER FLAGS 

$TRAN 

'PROTECTION',PARSE PROT,,PROT FLAG,PARSER FLAGS 

r + 

; Get file owner UIC. 

$STATE 

PARSEJJIC 

$TRAN 

/ . / 

$TRAN 

t — r 

$STATE 

$TRAN 

!UIC,OPTIONS 

+ 

Get number of 

directory entries. 

$STATE 

PARSE_ENTRIES 

$TRAN 

i • t 

$TRAN 

r — r 

$STATE 

$TRAN 

TPA$_DECIMAL,OPTIONS,,,ENTRY_COUNT 

+ 

Get directory 

file protection. Note that the bit masks generate the 

protection in 
program. 

complement form. It will be uncomplemented by the main 

$STATE 

PARSE_PROT 

$TRAN 

/ • f 

$TRAN 

r = r 

$STATE 

$TRAN 

f (' 

$STATE 

NEXT PRO 

$TRAN 

'SYSTEM', SYPR 
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$TRAN 'OWNER', OWPR 

$TRAN 'GROUP', GRPR 

$TRAN 'WORLD', WOPR 

$STATE SYPR 

$TRAN ':' 

$TRAN 

$STATE SYPRO 

$TRAN 'R',SYPRO,,SYSTEM_READ_FLAG,FILE_PROTECT 

$TRAN 'W',SYPRO,,SYSTEM_WRITE_FLAG,FILE_PROTECT 

$TRAN 'E',SYPRO,,SYSTEM_EXECUTE_FLAG,FILE_PROTECT 

$TRAN 'D',SYPRO,,SYSTEM_DELETE_FLAG,FILE_PROTECT 

$TRAN TPA$_LAMBDA,ENDPRO 

$STATE OWPR 

$TRAN ':' 

$TRAN 

$STATE OWPRO 

$TRAN 'R',OWPRO,,OWNER_READ_FLAG,FILE_PROTECT 

$TRAN 'W',OWPRO,,OWNER_WRITE_FLAG,FILE_PROTECT 

$TRAN 'E',OWPRO,,OWNER_EXECUTE_FLAG,FILE_PROTECT 

$TRAN 'D',OWPRO,,OWNER_DELETE_FLAG,FILE_PROTECT 

$ TRAN TPA$_LAMBDA,ENDPRO 

$STATE GRPR 

$TRAN ':' 

$TRAN 

$STATE GRPRO 

$TRAN 'R',GRPRO,,GROUP_READ_FLAG,FILE_PROTECT 

$TRAN 'W',GRPRO,,GROUP_WRITE_FLAG,FILE_PROTECT 

$TRAN 'E',GRPRO,,GROUP_EXECUTE_FLAG,FILE_PROTECT 

$TRAN 'D',GRPRO,,GROUP_DELETE_FLAG, FILE_PROTECT 

$TRAN TPA$_LAMBDA,ENDPRO 

$STATE WOPR 

$TRAN ':' 

$TRAN 

$STATE WOPRO 

$TRAN 'R',WOPRO,,WORLD_READ_FLAG,FILE_PROTECT 

$TRAN 'W',WOPRO,,WORLD_WRITE_FLAG,FILE_PROTECT 

$TRAN 'E',WOPRO,,WORLD_EXECUTE_FLAG,FILE_PROTECT 

$TRAN 'D',WOPRO,,WORLD_DELETE_FLAG,FILE_PROTECT 

$TRAN TPA$_LAMBDA,ENDPRO 

$STATE ENDPRO 

$TRAN <','>,NEXT_PRO 

$TRAN ')',OPTIONS 


Subexpression to parse a UIC string. 


$STATE 

UIC 


$TRAN 



$STATE 

$TRAN 

TPA$_OCTAL,, 

,,,UIC_GROUP 

$STATE 

$TRAN 

<V> 

; The comma character must be 
; surrounded by angle brackets 

; because MACRO restricts the use 

; of commas in arguments to macros 

$STATE 

$TRAN 

TPA$ OCTAL,, 

r ,,UIC_MEMBER 


LIB-469 




LIB$TPARSE/LIB$TABLE_PARSE 


$STATE 

$TRAN ']',TPA$_EXIT,CHECK_UIC 


Subexpression to parse a general directory string 



$ STATE 

NAME 



$TRAN 




$STATE 

NAMEO 



$TRAN 

TPA$_STRING,,STORE_NAME 



$ STATE 
$TRAN 

'.',NAMEO 



$TRAN 

']',TPA$_EXIT 



$END_STATE 




.SBTTL 

Parser Action Routines 



.PSECT 

CODE,EXE,NOWRT 


; + 

; Shut 

off explicit blank processing after passing the command name. 

BLANKS_ 

OFF: 




.WORD 

0 

No registers saved (or used) 


BBCC 

#TPA$V BLANKS,TPA$L OPTIONS(AP),10$ 

10$: 

RET 



; + 

; Check 

the UIC for 

legal value range. 


CHECK UIC: 




.WORD 

o ; 

No registers saved (or used) 


TSTW 

UIC GROUP+2 

UIC components are 16 bits 


BNEQ 

10$ 



TSTW 

UIC MEMBER+2 



BNEQ 

10$ 



MOVW 

UIC GROUP,FILE OWNER+2 ; 

Store actual UIC 


MOVW 

RET 

UIC_MEMBER,FILE_OWNER ; 

after checking 

10$: 

CLRL 

R0 ; 

Value out of range - fail 


RET 

r 

the transition 

; + 

; Store 

a directory 

name component. 


STORE NAME: 




.WORD 

0 

No registers saved (or used) 


MOVL 

NAME COUNT,R1 

Get count of names so far 


CMPL 

R1, #8 

Maximum of 8 permitted 


BGEQU 

10$ 



INCL 

NAME COUNT ; 

Count this name 


MOVAQ 

DIRNAME1[R1],R1 

Address of next descriptor 


MOVQ 

TPA$L TOKENCNT(AP),(Rl) ; 

Store the descriptor 


CMPL 

(R1),#9 ; 

Check the length of the name 


BGTRU 

RET 

10$ ; 

Maximum is 9 

10$: 

CLRL 

R0 ; 

Error in directory name 

; + 

RET 




; Convert a UIC into its equivalent directory file name. 
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MAKE UIC: 



.WORD 

0 

; No registers saved (or used) 

TSTB 

UIC GROUP+1 

; Check UIC for byte values, 

BNEQ 

10$ 

; Since UIC type directories 

TSTB 

UIC MEMBER+1 

; Are restricted to this form 

BNEQ 

10$ 


MOVL 

#6,DIRNAME1 

; Directory name is 6 bytes 

MOVAL 

UIC STRING,DIRNAME1+4 

; Point to string buffer 

$FAOL 

CTRSTR=FAO STRING,- 

; Convert UIC to octal string 


OUTBUF=DIRNAMEl,- 



PRMLST=UIC_GROUP 


RET 



10$: CLRL 

R0 

; Range error - fail it 

RET 




FAO_STRING: .LONG STRING_END-STRING_START 

STRING_START: .ASCII '!OB!OB' 

STRING END: 


END CREATE_DIR 

The preceding MACRO program accepts and parses the command line of a 
CREATE/DIRECTORY command. 
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LIB$TRA_ASC_EBC—Translate ASCII to EBCDIC 


The Translate ASCII to EBCDIC routine translates an ASCII string to an 
EBCDIC string. 


Format 


LIB$TRA_ASC_EBC source-string ,byte-integer-dest-string 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Arguments 


source-string 

OpenVMS usage 

type 

access 

mechanism 


char_string 
character string 
read only 
by descriptor 


Source string (ASCII) to be translated by LIB$TRA_ASC_EBC. The source¬ 
string argument contains the address of a descriptor pointing to this source 
string. 


byte-integer-dest-string 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor 

Destination string (EBCDIC). The byte-integer-dest-string argument contains 
the address of a descriptor pointing to this destination string. 


Description 

LIB$TRA_ASC_EBC translates an ASCII string to an EBCDIC string. If the 
destination string is a fixed-length string, its length must match the length of the 
input string. No filling is done. 

A similar operation can be accomplished by specifying the ASCII-to-EBCDIC 
translation table LIB$AB_ASC_EBC in a routine using LIB$MOVTC, but no 
testing for untranslatable characters is done under those circumstances. 

This routine uses the ASCII-to-EBCDIC translation table. 

ASCII to EBCDIC Translation Table 

• The number on the left represents the low-order bits of the ASCII character 
in hexadecimal notation. 

• The number across the top represents the high-order bits of the ASCII 
character in hexadecimal notation. 
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• The number in the body of the table represents the equivalent EBCDIC 
character in hexadecimal notation. 

Figure LIB—25 is the ASCII-to-EBCDIC Translation Table. 

Figure LIB-25 LIB$AB_ASC_EBC 


Row 

Bits 0-3 




Column 



Bits 4 - 

7 
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3F 

3F 

3F 

3F 
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1 
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D8 

81 
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3F 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

2 

02 

12 

7F 

F2 

C2 

D9 

82 

99 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

3 

03 

13 

7B 
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C3 
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3F 
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84 
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3F 

3F 

3F 

3F 
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6C 
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E4 

85 

A4 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

6 

2E 

32 

50 

F6 

C6 

E5 

86 

A5 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

7 

2F 

26 

7D 

F7 

C7 

E6 

87 

A6 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

8 

16 

18 

4D 

F8 

C8 

E7 

88 

A7 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

9 

05 

19 

5D 

F9 

C9 

E8 

89 

A8 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

A 

25 

3F 

5C 

7A 

D1 

E9 

91 

A9 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

B 

0B 

27 

4E 

5E 

D2 

4A 

92 

CO 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

C 

OC 

1C 

6B 

4C 

D3 

E0 

93 

6A 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

D 

0D 

ID 

60 

7E 

D4 

5A 

94 

DO 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

E 

0E 

IE 

4B 

6E 

D5 

5F 

95 

A1 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

F 

OF 

IF 

61 

6F 

D6 

6D 

96 

07 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

FF 
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All ASCII graphics are translated to their equivalent EBCDIC graphic except for 
the following: 


Table LIB-10 ASCII Graphics Not Translated to EBCDIC Equivalent by 
LIB$TRA_ASC_EBC 


ASCII Graphic 

EBCDIC Graphic 

[ (left square bracket) 

cents sign 

! (exclamation point) 

short vertical bar 

A (circumflex) 

logical not 

] (right square bracket) 

! (exclamation point) 


Condition Values Returned 

SS$_N ORMAL 
LIB$_INVCHA 


LIB$_INVARG 


Routine successfully completed. 

One or more occurrences of an untranslatable 
character have been detected during the 
translation. 

If the destination string is a fixed-length string 
and its length is not the same as the source 
string length, no translation is attempted. 
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Example 


IDENTIFICATION DIVISION. 
PROGRAM-ID. TRANS. 


ENVIRONMENT DIVISION. 

DATA DIVISION. 

WORKING-STORAGE SECTION. 

01 INPUT-STRING PIC X(4). 

01 EBCDIC-STRING PIC X(4). 

01 OUT-STRING PIC X(4). 

01 FILL-CHAR PIC X VALUE "G!". 

01 SS-STATUS PIC S9(9) COMP. 

88 SS-NORMAL VALUE 01. 


01 EBCDIC-TABLE. 


05 

FILLER 

PIC 

X (16) 

VALUE 

05 

FILLER 

PIC 

X (16) 

VALUE 

05 

FILLER 

PIC 

X( 16) 

VALUE 

05 

FILLER 

PIC 

X( 16) 

VALUE 

05 

FILLER 

PIC 

X(16) 

VALUE 

05 

FILLER 

PIC 

X (16) 

VALUE 

05 

FILLER 

PIC 

X( 16) 

VALUE 

05 

FILLER 

PIC 

X( 16) 

VALUE 

05 

FILLER 

PIC 

X( 16) 

VALUE 

05 

FILLER 

PIC 

X( 16) 

VALUE 

05 

FILLER 

PIC 

X (16) 

VALUE 

05 

FILLER 

PIC 

X( 16) 

VALUE 

05 

FILLER 

PIC 

X (16) 

VALUE 

05 

FILLER 

PIC 

X (16) 

VALUE 

05 

FILLER 

PIC 

X (16) 

VALUE 

05 

FILLER 

PIC 

X( 16) 

VALUE 




»@@@@@@@@@@@@@@@@». 

"&@@@@@@@@@ !$*) . 

"@@@@@@@@@@;#@ ' = """ 
"@abcdefghi@@@@@@". 
"@jklmnopqr@@@@@@". 
"@@stuvwxyz@@@@@@". 
" 0000000000000000 ". 
"@ABCDEFGHI@ @ @ @ @ @" . 
"!JKLMNOPQR@@@@@@". 
"@@STUVWXYZ@@@@@@". 
"0123456789@@@@@@". 


ROUTINE DIVISION. 


001-MAIN. 

DISPLAY " 

DISPLAY "ENTER 4 CHARACTERS TO BE TRANSLATED ASCII TO EBCDIC 
WITH NO ADVANCING. 

ACCEPT INPUT-STRING 
AT END STOP RUN. 

IF INPUT-STRING = "EXIT" OR "exit" OR " 

STOP RUN. 

CALL "LIB $ TRA_ASC_EBC" 

USING BY DESCRIPTOR INPUT-STRING, EBCDIC-STRING 
GIVING SS-STATUS. 

IF SS-NORMAL 

CALL "LIB$MOVTC" 

USING BY DESCRIPTOR EBCDIC-STRING, 

FILL-CHAR, 

EBCDIC-TABLE, 

OUT-STRING, 

GIVING SS-STATUS 
IF SS-NORMAL 

DISPLAY "ASCII ENTERED WAS: " INPUT-STRING 
DISPLAY "EBCDIC TRANSLATED IS: " OUT-STRING 
ELSE 

DISPLAY "*** LIB$MOVTC TRANSLATION UNSUCCESSFUL ***" 

ELSE 

DISPLAY "*** LIB$TRA_ASC_EBC TRANSLATION UNSUCCESSFUL ** 
GO TO 001-MAIN. 
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This COBOL program uses LIB$TRA_ASC_EBC to translate an ASCII string to 
EBCDIC. If successful, it then uses LIB$MOVTC to translate the EBCDIC string 
back to ASCII. 

To exit from this program, you must type Ctrl/z. The output generated by this 
COBOL program is as follows: 

$ RUN TRANS 

ENTER 4 CHARACTERS TO BE TRANSLATED ASCII TO EBCDIC: abdc 
ASCII ENTERED WAS: abdc 
EBCDIC TRANSLATED IS: abdc 

ENTER 4 CHARACTERS TO BE TRANSLATED ASCII TO EBCDIC: -=b& 

ASCII ENTERED WAS: ~=b& 

EBCDIC TRANSLATED IS: @=b& 

ENTER 4 CHARACTERS TO BE TRANSLATED ASCII TO EBCDIC: 8 A %$ 

ASCII ENTERED WAS: 8 A %$ 

EBCDIC TRANSLATED IS: 8@%$ 

ENTER 4 CHARACTERS TO BE TRANSLATED ASCII TO EBCDIC: 

/x\> 

ASCII ENTERED WAS: /x\} 

EBCDIC TRANSLATED IS: /x§! 

ENTER 4 CHARACTERS TO BE TRANSLATED ASCII TO EBCDIC: Ctrl/z 
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LIB$TRA_EBC_ASC—Translate EBCDIC to ASCII 

The Translate EBCDIC to ASCII routine translates an EBCDIC string to an 
ASCII string. 

Format 

UB$TRA_EBC_ASC byte-integer-source-string ,destination-string 

Returns 

OpenVMS usage cond_value 
type longword (unsigned) 

access read only 

mechanism by value 


Arguments 

byte-integer-source-string 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

String (EBCDIC) to be translated by LIB$TRA_EBC_ASC. The byte-integer- 
source-string argument contains the address of a descriptor pointing to this 
source string. 

destination-string 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor 

Destination string (ASCII). The destination-string argument contains the 
address of the descriptor of this destination string. 

This routine uses the EBCDIC-to-ASCII translation table LIB$AB_EBC_ASC. 


Description 

LIB$TRA_EBC_ASC translates an EBCDIC string to an ASCII string. If the 
destination string is a fixed-length string, its length must match the length of the 
input string. No filling is done. 

A similar operation can be accomplished by specifying the EBCDIC-to-ASCII 
translation table LIB$AB_EBC_ASC in a routine using LIB$MOVTC, but no 
testing for untranslatable characters is done under these circumstances. 

This routine uses the EBCDIC-to-ASCII translation Figure LIB-26. 
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Figure LIB-26 LIB$AB_EBC_ASC 
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Bits 0-3 
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Bits 4 - 
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61 
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31 

2 
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12 
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IB 
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5C 

5C 

5C 

67 

70 

78 

5C 

47 

50 

58 

37 

8 

5C 

18 
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5C 

5C 

68 

71 

79 

5C 

48 

51 

59 

38 

9 

5C 

19 
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5C 
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5C 

2E 

24 

2C 

23 

5C 
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5C 

5C 

C 

OC 

1C 

5C 

14 

3C 

2A 

25 

40 

5C 

5C 

5C 

5C 

5C 

5C 

5C 

5C 

D 

0D 

ID 

05 

15 

28 

29 

5F 

27 

5C 

5C 

5C 

5C 

5C 

5C 

5C 

5C 

E 

0E 

IE 

06 

5C 

2B 

3B 

3E 

3D 

5C 

5C 

5C 

5C 

5C 

5C 

5C 

5C 

F 

OF 

IF 

07 

1A 

21 

5E 

3F 

22 

5C 

5C 

5C 

5C 

5C 

5C 

5C 

FF 
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EBCDIC to ASCII Translation Table 

• The number on the left represents the low-order bits of the EBCDIC character 
in hexadecimal notation. 

• The number across the top represents the high-order bits of the EBCDIC 
character in hexadecimal notation. 

• The number in the body of the table represents the equivalent ASCII 
character in hexadecimal notation. 

All EBCDIC graphics are translated to their equivalent ASCII graphic except for 

the following: 


Table LIB-11 EBCDIC Graphics Not Translated to ASCII Equivalent by 
LIB$TRA_EBC_ASC 


EBCDIC Graphic 

ASCII Graphic 

cents sign 

[ (left square bracket) 

short vertical bar 

! (exclamation point) 

logical not 

A (circumflex) 

! (exclamation point) 

] (right square bracket) 


Condition Values Returned 

SS$_NORMAL Routine successfully completed. 

LIB$_INVCHA One or more occurrences of an untranslatable 

character have been detected during the 
translation. 
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LIB$_INVARG If the destination string is a fixed-length string 

and its length is not the same as the source 
string length, no translation is attempted. 
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LIB$TRAVERSE_TREE—Traverse a Balanced Binary Tree 

The Traverse a Balanced Binary Tree routine calls an action routine for each node 
in a binary tree. 


Format 

LIB$TRAVERSE_TREE treehead ,user-action-procedure [,user-data-address] 

Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Arguments 


treehead 

OpenVMS usage 

type 

access 

mechanism 


address 
address 
read only 
by reference 


Tree head of the binary tree. The treehead argument is the address of an 
unsigned longword that is the tree head in the binary tree traversal. 


user-action-procedure 

OpenVMS usage procedure 
type procedure value 

access function call (before return) 

mechanism by value 

User-supplied action routine called by LIB$TRAVERSE_TREE for each 
node in the tree. User-action-procedure must return a success status for 
LIB$TRAVERSE_TREE to continue traversal. 

For more information, see “Call Format for an Action Routine” in the Description 
section. 


user-data-address 

OpenVMS usage user_arg 
type longword (unsigned) 

access read only 

mechanism by reference 

User data that LIB$TRAVERSE_TREE passes to your action routine. The 
user-data-address argument contains the address of this user data. This is an 
optional argument; the default value is zero. 
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Description 

LIB$TRAVERSE_TREE calls a user-supplied action routine for each node to 
traverse a balanced binary tree. 

Call Format for an Action Routine 

The format of the call is as follows: 

user-action-procedure node ,user-data-address 

LIB$TRAVERSE_TREE passes the node and user-data-address arguments to 
your action routine by reference. 

This action routine is defined by you to fit your own purposes. A common use 
of an action routine here is to print the contents of each node during the tree 
traversal. 

This is one example of a user-supplied action routine. 

1 %TITLE 'LIBS Tree Example in BASIC V2' 

%SBTTL 'Function to display a node' 

FUNCTION LONG PRINT_NODE (NODE_TYPE NODE, LONG DUMMY) 

! + 

! Print the string contained in the current node 

i _ 


OPTION TYPE = EXPLICIT 
RECORD NODEJTYPE 

BYTE HEADER (9) ! Header 

BYTE LENGTH ! Length 

STRING TEXT = 80 ! String 

END RECORD NODE_TYPE 

PRINT SEG$ (NODE::TEXT, 1%, NODE::LENGTH) 

PRINT_NODE =1% 

END FUNCTION 


Condition Values Returned 


LIB$_NORMAL Success. Traversal complete. 

Any condition value returned by your action routine. 


Example 


The BASIC example provided in the description of LIB$INSERT_TREE also 
demonstrates the use of LIB$TRAVERSE_TREE. Please refer to that example for 
assistance in using this routine. 
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L1B$TRIM_FILESPEC—Fit Long File Specification into Fixed Field 

The Fit Long File Specification into Fixed Field routine takes a file specification, 
such as an RMS resultant name string, and shortens it (if necessary) so that it 
fits into a field of fixed width. 

Format 

UB$TRIM_FILESPEC old-filespec ,new-filespec [,word-integer-width] [,resultant-length] 

Returns 

OpenVMS usage 
type 
access 
mechanism 

Arguments 

old-filespec 

OpenVMS usage char_string 
type character string 

access read only 

mechanism by descriptor 

File specification to be trimmed. The old-filespec argument contains the address 
of a descriptor pointing to this file specification string. 

The file specification should be an RMS resultant name string. The error LIB$_ 
INVARG is returned if old-filespec contains more than 255 characters. 

new-filespec 

OpenVMS usage char_string 
type character string 

access write only 

mechanism by descriptor 

Trimmed file specification. The new-filespec argument contains the address 
of a descriptor pointing to this trimmed file specification string. LIB$TRIM_ 
FILESPEC writes the trimmed file specification into new-filespec. 

word-integer-width 

OpenVMS usage word_unsigned 
type word (unsigned) 

access read only 

mechanism by reference 

Maximum field width desired. The word-integer-width argument is the address 
of an unsigned word that contains this maximum field width. 

If omitted, the current length of new-filespec is used. If new-filespec is not a 
fixed-length string, you should specify word-integer-width to ensure that the 
desired width is used. 


cond_value 
longword (unsigned) 
write only 
by value 
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resultant-length 

OpenVMS usage word_unsigned 
type word (unsigned) 

access write only 

mechanism by reference 

Length of the trimmed file specification, not including any blank padding or 
truncated characters. The resultant-length argument is the address of an 
unsigned word that contains this length. This is an optional argument. 


Description 

This routine trims file specifications in a consistent, predictable manner to fit in a 
fixed-length field using the same algorithm that Digital software uses. 

LIB$TRIM_FILESPEC allows compilers and other utilities which need to display 
file specifications in fixed-length fields, such as listing headers, to display file 
specifications in a consistent fashion. 

If necessary to make the file specification fit into the specified field width, 
LIB$TRIM_FILESPEC removes portions of the file specification in this order. 

1. Node (including access control) 

2. Device 

3. Directory 

4. Version 

5. Type 

If, after removing all these fields, the file name is still longer than the field width, 
the file name is truncated and the alternate success status LIB$_STRTRU is 
returned. 

LIB$TRIM_FILESPEC supports any string class for the old-filespec and 
new-filespec string arguments. 


Condition Values Returned 


SS$_NORMAL 

LIB$_STRTRU 


LIB$_INVARG 

LIB$_INVSTRDES 

LIB$_WRONUMARG 


Routine successfully completed. 

Success, but the output string was truncated. 
Significant characters of the trimmed file 
specification were truncated. 

Invalid argument. Old-filespec contained more 
than 255 characters. 

Invalid string descriptor. 

Wrong number of arguments. 


Any condition values returned by LIB$SCOPY_R_DX. 


Any condition values returned by the $FILESCAN system service. 
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Example 


PROGRAM TRIM_FILESPEC(INPUT,OUTPUT); 

{ + } 

{ This PASCAL example program demonstrates the 
{ use of LIB$TRIM_FILESPEC. 

{-} 


TYPE 

WORD = [WORD] 0..65535; 

VAR 

INPUT_FILESPEC : VARYING [255] OF CHAR; 
OUTPUT_FILESPEC : VARYING [32] OF CHAR; 
RETURNED_STATUS : INTEGER; 

[EXTERNAL] FUNCTION LIB$TRIM_FILESPEC( 

IN_FILE : VARYING [LEN1] OF CHAR; 

VAR OUT_FILE : VARYING [LEN2] OF CHAR; 

WIDTH : WORD := %IMMED 0; 

OUT_LEN : [REFERENCE] WORD := %IMMED 0 

) : INTEGER; EXTERNAL; 

[EXTERNAL] FUNCTION LIB$STOP( 

CONDITION_STATUS : [IMMEDIATE,UNSAFE] UNSIGNED; 
FAO_ARGS : [IMMEDIATE,UNSAFE,LIST] UNSIGNED 

) : INTEGER; EXTERNAL; 


BEGIN 
{ + } 

{ Start with a large INPUT_FILESPEC. 

{-} 

INPUT_FILESPEC := 'DISK$NAME:[DIRECTORY1.DIRECTORY2]FILENAME.EXTENSION;1'; 

{ + } 

{ Use LIB$TRIM_FILESPEC to shorten it to fit a smaller variable. 

{-} 

RETURNED_STATUS := LIB$TRIM_FILESPEC( 

INPUT_FILESPEC, 

OUTPUT_FILESPEC, 

SIZE(OUTPUT_FILESPEC.BODY)); 

IF NOT ODD(RETURNED_STATUS) 

THEN 

LIB$STOP(RETURNED_STATUS); 

{ + } 

{ Print out the original file name along with the 
{ shortened file name. 

{-} 

WRITELN('Original file specification ',INPUT_FILESPEC); 

WRITELN('Shortened file specification ',OUTPUT_FILESPEC); 

END. 

This PASCAL example program demonstrates the use of LIB$TRIM_FILESPEC. 
The output generated by this program is as follows: 

Original file specification DISK$NAME:[DIRECTORY1.DIRECTORY2]FILENAME.EXTENSION;1 
Shortened file specification FILENAME.EXTENSION;1 
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LIB$VERIFY_VM_ZONE—Verify a Zone 

The Verify a Zone routine performs verification of a zone. 


Format 

LIB$VERIFY_VM_ZONE zone-id 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Argument 


zone-id 

OpenVMS usage 

type 

access 

mechanism 


identifier 

longword (unsigned) 
read only 
by reference 


Zone identifier of the zone to be verified. The zone-id argument is the address of 
an unsigned longword that contains this zone identifier. A value of zero indicates 
the default zone. 


Description 

LIB$VERIFY_VM_ZONE verifies a zone. LIB$VERIFY_VM_ZONE performs 
verification of the zone header and scans all of the queues and lists maintained 
in the zone header; this includes the lookaside lists and the free lists. If the 
zone was created with LIB$M_VM_FREE_FILLO or LIB$M_VM_FREE_FILL1, 
LIB$VERIFY_VM_ZONE also checks the contents of the free blocks. 

As soon as an error is encountered, processing stops. If LIB$_BADZONE is 
returned, use the routine LIB$SHOW_VM_ZONE to dump the zone information. 

You must have exclusive access to the zone while the verification is proceeding. 
Results are unpredictable if another thread of control modifies the zone while this 
routine is analyzing control data or scanning control blocks. 


Condition Values Returned 

SS$_N ORMAL 
LIB$_BADZONE 
LIB$_INVARG 
LIB$_WRONUMARG 


Normal successful completion. 
Invalid zone. 

Invalid or null argument. 
Wrong number of arguments. 
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LIB$WAIT—Wait a Specified Period of Time 

The Wait a Specified Period of Time routine places the current process into 
hibernation for the number of seconds specified in its argument. 


Format 

LIB$WAIT seconds 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Argument 


seconds 

OpenVMS usage 

type 

access 

mechanism 


floating_point 
F_floating 
read only 
by reference 


The number of seconds to wait. The seconds argument contains the address of 
an F-floating number that is this number. 

The value is rounded to the nearest hundredth-second before use. Seconds must 
be between 0.0 and 100,000.0. 


Description 

LIB$WAIT rounds the value specified by seconds to the nearest hundredth- 
second, uses the $SCHDWK system service to schedule a wakeup for that 
interval, and then issues the $HIBER system service to hibernate until the 
wakeup occurs. 

Due to other system activity, the length of time that the process actually waits 
may be somewhat longer than what was specified by seconds. 

The process hibernates in the caller’s access mode; therefore, asynchronous 
system traps (ASTs) may be delivered while the process is hibernating. However, 
if the process hibernates at AST level, further ASTs can not be delivered. See the 
OpenVMS System Services Reference Manual for more information. 

Condition Values Returned 

SS$_NORMAL Routine successfully completed. 

LIB$_INVARG Invalid argument. The value of seconds was 

less than zero or was greater than 100,000.0 

LIB$_WRONUMARG Wrong number of arguments. An incorrect 

number of arguments was passed to LIB$WAIT. 

Any condition values returned by the $SCHDWK system service. 
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Example 


IDENTIFICATION DIVISION. 

PROGRAM-ID. SAMPLE. 

DATA DIVISION. 

WORKING-STORAGE SECTION. 

01 DELAY COMP-1. 

ROUTINE DIVISION. 

START-SAMPLE. 

MOVE 3.5 TO DELAY. 

CALL "LIB$WAIT" 

USING BY REFERENCE DELAY. 

STOP RUN. 

This COBOL program demonstrates the use of LIB$WAIT. When run, it waits for 
3.5 seconds and then exits. 


LIB-486 



CVT$ Reference Section 


This section provides a detailed discussion of the routine provided by the 
OpenVMS RTL (CVT$) Facility. 




CVT$CONVERT_FLOAT 


CVT$CONVERT_FLOAT—Convert Floating Point Data Type 

(OpenVMS AXP Only) 


AXP 


Format 


On OpenVMS AXP systems, the CVT$CONVERT_FLOAT routine converts 
floating point data types to other supported floating point data types. 


CVT$CONVERT_FLOAT input_value, input_type_code, output_value, output_type_code, options 


Returns 


OpenVMS usage 

type 

access 

mechanism 


cond_value 
longword (unsigned) 
write only 
by value 


Argument 


input_value 

OpenVMS usage 

type 

access 

mechanism 


varying_arg 
unspecified 
read only 
by reference 


The input_value argument is the address of a data area containing a floating 
point number that is to be converted. The input_value argument may contain 
floating point data in F_Floating, D_floating, G_Floating, H_Floating, IEEE_S_ 
Floating, IEEE_T_Floating, IBM_Long_Floating, IBM_Short_Floating, or Cray. 
Floating format. The value of the input_type_code argument determines the 
format and size of the input_value argument. 


1 n put__ty pe_code 

Format 

Size in Bytes 

CVT$K_VAX_F 

F_Floating 

4 

CVT$K_VAX_D 

D_Floating 

8 

CVT$K_VAX_G 

G_Floating 

8 

CVT$K_VAX_H 

H_Floating 

16 

CVT$K_IEEE_S 

IEEE_S_Floating 

4 

CVT$K_IEEE_T 

IEEE_T_Floating 

8 

C VT$K_IB M_SH ORT 

IBM_Short_Floating 

4 

C VT$K_IBM_LON G 

IBM_Long_Floating 

8 

CVT$K_CRAY 

Cray_Floating 

8 


input_type_code 

OpenVMS usage 

type 

access 

mechanism 


mask_longword 
longword (unsigned) 
read only 
by value 
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CVT$CONVERT_FLOAT 


The address of a longword bit mask specifying the type of floating point data 
being passed in the input_value argument. Valid type codes are: 

CVT$K_VAX_F 

CVT$K_VAX_D 

CVT$K_VAX_G 

CVT$K_VAX_H 

CVT$K_IEEE_S 

CVT$K_IEEE_T 

C VT$K_IBM_LON G 

CVT$K_IBM_SHORT 

CVT$K_CRAY 

output__value 

OpenVMS usage varying_arg 
type unspecified 

access write only 

mechanism by reference 

The output_value argument is the address a of data area that will receive the 
converted floating point number. The output_value argument can contain floating 
point data in F_Floating, D_floating, G_Floating, H_Floating, IEEE_S_Floating, 
IEEE_T_Floating, IBM_Long_Floating, IBM_Short_Floating, or Cray_Floating 
format. The value of the output_type_code argument determines the size and 
format of the data placed into the output_value argument. 


Output_type_code 

Format 

Size in Bytes 

CVT$K_VAX_F 

F_Floating 

4 

CVT$K_VAX_D 

D_Floating 

8 

CVT$K_VAX_G 

G_Floating 

8 

CVT$K_VAX_H 

H_Floating 

16 

CVT$K_IEEE_S 

IEEE_S_Floating 

4 

CVT$K_IEEE_T 

IEEE_T_Floating 

8 

CVT$K_IBM_SHORT 

IBM_Short_Floating 

4 

C VT$K_IBM_LON G 

IBM_Long_Floating 

8 

CVT$K_CRAY 

Cray_Floating 

8 


output__type_code 

OpenVMS usage mask_longword 
type longword (unsigned) 

access read only 

mechanism by value 

The address of a longword bit mask specifying the type of floating point data that 
the input_value argument will be converted into and returned in the output_value 
argument. Valid type codes are: 

CVT$K_VAX_F 

CVT$K_VAX_D 

CVT$K_VAX_G 

CVT$K_VAX_H 

CVT$K_IEEE_S 

CVT$K_IEEE_T 
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C VT$K_IBM_LON G 
CVT$K_IBM_SHORT 
C VT$K_C RAY 


options 

OpenVMS usage mask_longword 
type longword (unsigned) 

access read only 

mechanism by value 

Conversion option specifier. The options argument is the address of a longword 
bit mask in which each option bit set causes the corresponding option to be used 
during the conversion. 

The following options can be specified using the options argument: 

CVT$M_ROUND_TO_NEAREST 
C VT$M_TRUN CATE 
CVT$M_ROUND_TO_POS 
CVT$M_ROUND_TO_NEG 
C VT$M_VAX_ROUNDIN G 

cvt$m_big_endian 

CVT$M_ERR_UNDERFLOW 


Description 

CVT$CONVERT_FLOAT is a general purpose floating point conversion routine 
that will convert any one of the floating point data types that are listed below 
into any of the other floating point data types. The conversion will be subject 
to the options specified in the OPTIONS mask argument. The following floating 
point data types are supported: 


VAX F Floating 
VAX D Floating 
VAX G Floating 
VAX H Floating 
IEEE S Floating 
IEEE T Floating 
IBM Short Floating 
IBM Long Floating 
Cray Floating 


( 4 bytes) 
( 8 bytes) 
( 8 bytes) 
(16 bytes) 
( 4 bytes) 
( 8 bytes) 
( 4 bytes) 
( 8 bytes) 
( 8 bytes) 


_ Note _ 

OpenVMS compilers do not support arithmetic operations for all of the 
above floating point data types. Additional floating point data types are 
supported by this routine for data conversion purposes only. (See the 
following program example for one use for supporting non OpenVMS data 
types.) 
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Condition Values Returned 

C VT$_N ORMAL 

CVT$_INPCONERR 

CVT$_INVINPTYP 

C VT$_INV OPT 

C VT$_INV OUTTYP 

CVT$_INWAL 

CVT$_NEGINF 

CVT$_OUTCONERR 

CVT$_OVERFLOW 

CVT$_POSINF 

CVT$_UNDERFLOW 


Normal successful completion. 

Input conversion error. 

Invalid input type code. 

Invalid option argument. 

Invalid output type code. 

Input value was an invalid number or NaN, 
Input value was negative infinity. 

Output conversion error. 

Overflow detected during conversion. 

Input value was positive infinity. 

Underflow detected during conversion. 


Example 


/* 

** ================================================================= 

** 

** Example of CVT$CONVERT_FLOAT 
** 

** _ 

** 

** This example program reads IEEE T floating point numbers from an 
** input file, converts them to VAX D floating point numbers and 
** writes the result to an output file. 

** 

** The input and output filenames can be specified as the first and 
** second arguments on the command line as follows: 

** 

** $ EXAMPLE IEEE__T_INPUT_FILE.DAT VAX_D_OUTPUT_FILE.DAT 

** 

** If the input and/or output files are not included on the command 
** line then the program will prompt the user for them. 

* * 

** =================================================================: 

*/ 

tinclude <stdio.h> 

unsigned long CVT$CONVERT_FLOAT(void *input value, 

unsigned long Tnput_type, 
void *output_value, 
unsigned long output_type, 
unsigned long options); 


globalvalue CVT$K_VAX_D; 
globalvalue CVT$K_IEEE_T; 
globalvalue CVT$M_ROUND_TO_NEAREST; 
globalvalue CVT$_NORMAL; 

main(int argc, char *argv[]) 

{ 
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double 

unsigned 

unsigned 

char 

char 

FILE 

unsigned 


D_Float_number; 
long IEEE_Double_number[2]; 
long options; 

in_filename[80]; 
out_filename[80]; 
*in_file, *out_file; 
long ret_status; 


/* 

** Find out where we are going to get the data from. 

** First look at the first argument of the command line. 
** If nothing is there then attempt to use IEEE_T_IN.DAT. 
* * ====================================================== 

*/ 

if (argc == 1) 

{ 

printf("Enter input data file: [IEEE_T_IN.DAT]: "); 
if (gets(in_filename) == NULL) 
exit(1); 


if (strlen(in_filename) == 0) 

strcpy(in_filename, "IEEE_T_IN.DAT"); 

} 

else 

strcpy(in_filename, argv[l]); 

/* 

** Find out where we are going to put the output data. 

** First look at the second argument of the command line. 
** If nothing is there then put it in VAX_D_OUT.DAT 
* * ====================================================== 

*/ 

if (argc <= 2) 

{ 

printf("Enter output data file: [VAX_D_OUT.DAT]: "); 
if (gets(out_filename) == NULL) 
exit(1); 


if (strlen(out_filename) == 0) 

strcpy(out_filename, "VAX_D_OUT.DAT"); 

} 

else 

strcpy(out_filename, argv[2]); 

/* 

** Open the input and output files. 


*/ 

if ((in_file = fopen(in_filename, "r")) == NULL) 

{ 

fprintf(stderr, "%s couldn't open file %s\n", argv[0], in_filename); 
exit(1); 

} 

out_file = fopen(out_filename, "wb"); 

options = CVT$M_ROUND_TO_NEAREST; 
ret_status = CVT$_NORMAL; 
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/* 

** Read in each number from the file, convert it, and write it to 
** the output file. 

** ================================================================= 

*/ 

while ((fread (&IEEE_Double_number[0], 

sizeof(IEEE_Double_number), 

1, 

in_file) == 1) && 

(ret_status == CVT$_NORMAL)) 

{ 

ret_status = CVT$CONVERT_FLOAT(&IEEE_Double_number[0], CVT$K_IEEE_T, 

&D_Float_number, CVT$K_VAX_D, 
options); 

fwrite(&D_Float_number, sizeof(D_Float_number), 1, out_file); 
printf("Converted data: %lf.\n", D_Float_number); 

} 

fclose(in_file); 
fclose(out_file); 

if (ret_status == CVT$_NORMAL) 
exit(1); 
else 

exit(ret_status); 

} 





Index 


A_ 

Addition 

quadword times, LIB—5 
two’s complement, LIB-7 
$ASCTIM 

RTL jacket routine, LIB-414 

_ 

Bit fields 

replace field, LIB—260 

return sign extended to longword, LIB—140 

C_ 

CALLG (Call Routine with General Argument 
List) instruction 
RTL routine to access, LIB-23 
Character string routines 
LIB$CHAR, LIB-25 
CLI symbols, LIB-359 
deleting, LIB-114 
getting value of, LIB-208 
RTL routines, LIB-114, LIB-208 
Condition handlers 

establishment, LIB-138 
Condition values, LIB-278 
Conversions 

numeric text to binary, LIB-74 
CVT$CONVERT_FLOAT routine, CVT-3 
Cyclic redundancy check tables, LIB—33 

D_ 

Date/Time routines 

LIB$DATE_TIME, LIB-78 
LIB$DAY, LIB-79 
LIB$DAY_OF_WEEK, LIB-81 
Decimal overflow detection, LIB—102 
Decimal text 

converting to binary, LIB-74 
Directories 

creation of, LIB-36 
Division 

extended precision, LIB-124 


E_ 

EDIV (Extended Divide) instructions 
RTL routine to access, LIB—124 
EMODD instructions 

RTL routine to access, LIB-126 
EMODF instructions 

RTL routine to access, LIB-128 
EMODG instructions 

RTL routine to access, LIB-130 
EMODH instructions 

RTL routine to access, LIB-132 
EMUL (Extended Multiply) instructions 
RTL routine to access, LIB-134 
Event flags 

RTL routine to free, LIB—173 

F_ 

$FAO 

RTL jacket routine for, LIB-416 
Faults 

fix floating reserved operands, LIB-162 
FFx instructions 

RTL routine to access, LIB-145 

H_ 

Hexadecimal text 

converting to binary, LIB—74 
Hibernation 

LIB$WAIT, LIB-485 

| _ 

Integer overflow, LIB-262 
Invocation context 

access routines, LIB-189, LIB-201, LIB-202, 
LIB-206, LIB-207, LIB-324 
functions, LIB—189, LIB—201, LIB-202, 
LIB-206, LIB-207, LIB-324 
obtaining handle, LIB-202 
updating, LIB-324 
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K_ 

Keywords 

in keyword table, LIB-268 

L_ 

LIB$ADAWI routine, LIB—3 
LIB$ADDX routine, LIB—7 
LIB$ADD_TIMES routine, LIB-5 
LIB$ANALYZE_SDESC routine, LIB-10 
LIB$ASN_WTH_MBX routine, LIB-12 
LIB$AST_IN_PROG routine, LIB-15 
LIB$ATTACH routine, LIB-17 
LIB$BBCCI routine, LIB-19 
LIB$BBSSI routine, LIB-21 
LIB$CALLG routine, LIB-23 
LIB$CHAR routine, LIB-25 
LIB$CONVERT_DATE_STRING routine, LIB-27 
LIB$CRC routine, LIB—31 
LIB$CRC_TABLE routine, LIB-33 
LIB$CREATE_DIR routine, LIB—36 
LIB$CREATE_USER_VM_ZONE routine, LIB-40 
LIB$CREATE_VM_ZONE routine, LIB-43 
LIB$CRF_INS_KEY routine, LIB-48 
LIB$CRF_INS_REF routine, LIB-50 
LIB$CRF_OUTPUT routine, LIB-53 
LIB$CURRENCY routine, LIB-57 
LIB$CVTF_FROM_INTERNAL_TIME routine, 
LIB-68 

LIB$CVTF_TO_INTERNAL_TIME routine, 

LIB-72 

LIB$CVT_DTB routine, LIB-74 
LIB$CVT_DX_DX routine, LIB-59 
LIB$CVT_FROM_INTERNAL_TIME routine, 
LIB-65 

LIB$CVT_HTB routine, LIB-74 
LIB$CVT_OTB routine, LIB-74 
LIB$CVT_TO_INTERNAL_TIME routine, LIB-70 
LIB$CVT_VECTIM routine, LIB-76 
LIB$DATE_TIME routine, LIB-78 
LIB$DAY routine, LIB—79 
LIB$DAY_OF_WEEK routine, LIB-81 
LIB$DECODE_FAULT routine, LIB-83 
LIB$DEC_OVER routine, LIB-102 
LIB$DELETE_FILE routine, LIB-104 
LIB$DELETE_LOGICAL routine, LIB-112 
LIB$DELETE_SYMBOL routine, LIB-114 
LIB$DELETE_VM_ZONE routine, LIB-116 
LIB$DIGIT_SEP routine, LIB-118 
LIB$DISABLE_CTRL routine, LIB-120 
LIB$DO_COMMAND routine, LIB-122 
LIB$EDIV routine, LIB-124 
LIB$EMODD routine, LIB—126 
LIB$EMODF routine, LIB-128 


LIB$EMODG routine, LIB—130 
LIB$EMODH routine, LIB—132 
LIB$EMUL routine, LIB-134 
LIB$ENABLE_CTRL routine, LIB—136 
LIB$ESTABLISH routine, LIB-138 
LIB$EXTV routine, LIB—140 
LIB$EXTZV routine, LIB-143 
LIB$FFC routine, LIB—145 
LIB$FFS routine, LIB—145 
LIB$FID_TO_NAME routine, LIB—147 
LIB$FILE_SCAN routine, LIB-149 
LIB$FILE_SCAN_END routine, LIB-151 
LIB$FIND_FILE routine, LIB—153 
LIB$FIND_FILE_END routine, LIB-156 
LIB$FIND_IMAGE_SYMBOL routine, LIB-157 
LIB$FIND_VM_ZONE routine, LIB-160 
LIB$FIXUP_FLT routine, LIB-162 
LIB$FLT_UNDER routine, LIB—164 
LIB$FORMAT_DATE_TIME routine, LIB-166 
LIB$FORMAT_SOGW_PROT routine, LIB-169 
LIB$FREE_DATE_TIME_CONTEXT routine, 
LIB-172 

LIB$FREE_EF routine, LIB-173 
LIB$FREE_LUN routine, LIB-174 
LIB$FREE_TIMER routine, LIB-175 
LIB$FREE_VM routine, LIB-176 
LIB$FREE_VM_PAGE routine, LIB-178 
LIB$GETDVI routine, LIB-216 
LIB$GETJPI routine, LIB—221 
LIB$GETQUI routine, LIB-225 
LIB$GETSYI routine, LIB-230 
LIB$GET_ACCNAM routine, LIB-180 
LIB$GET_ACCNAM_BY_CONTEXT routine, 
LIB-182 

LIB$GET_COMMAND routine, LIB-184 
LIB$GET_COMMON routine, LIB-187 
LIB$GET_CURR_INV0_CONTEXT routine, 
LIB-189 

LIB$GET_DATE_FORMAT routine, LIB-190 
LIB$GET_EF routine, LIB-192 
LIB$GET_FOREIGN routine, LIB-194 
LIB$GET_INPUT routine, LIB-198 
LIB$GET_INV0_C0NTEXT routine, LIB-201 
LIB$GET_INVO_HANDLE routine, LIB-202 
LIB$GET_LUN routine, LIB-203 
LIB$GET_MAXIMUM_DATE_LENGTH routine, 
LIB-204 

LIB$GET_PREV_INVO_CONTEXT routine, 
LIB-206 

LIB$GET_PREV_INVO_HANDLE routine, 
LIB-207 

LIB$GET_SYMBOL routine, LIB-208 
LIB$GET_USERS_LANGUAGE routine, LIB-211 
LIB$GET_VM routine, LIB-212 
LIB$GET_VM_PAGE routine, LIB-214 
LIB$ICHAR routine, LIB—234 
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LIB$INDEX routine, LIB-236 
LIB$INIT_DATE_TIME_CONTEXT routine, 
LIB-238 

LIB$INIT_TIMER routine, LIB-242 
LIB$INSERT_TREE routine, LIB-244 
LIB$INSQHI routine, LIB-255 
LIB$INSQTI routine, LIB-258 
LIB$INSV routine, LIB-260 
LIB$INT_OVER routine, LIB—262 
LIB$LEN routine, LIB—264 
LIB$LOCC routine, LIB-265 
LIB$LOOKUP_KEY routine, LIB-268 
LIB$LOOKUP_TREE routine, LIB-272 
LIB$LP_LINES routine, LIB-274 
LIB$MATCHC routine, LIB-276 
LIB$MATCH_COND routine, LIB-278 
LIB$MOVC3 routine, LIB-281 
LIB$MOVC5 routine, LIB-283 
LIB$MOVTC routine, LIB-285 
LIB$MOVTUC routine, LIB-302 
LIB$MULTF_DELTA_TIME routine, LIB-306 
LIB$MULT_DELTA_TIME routine, LIB-305 
LIB$PARSE_ACCESS_CODE routine, LIB-307 
LIB$PARSE_SOGW_PROT routine, LIB-309 
LIB$PAUSE routine, LIB-312 
LIB$POLYD routine, LIB-313 
LIB$POLYF routine, LIB-315 
LIB$POLYG routine, LIB-318 
LIB$POLYH routine, LIB-320 
LIB$PUT_COMMON routine, LIB-322 
LIB$PUT_INVO_REGISTERS routine, LIB-324 
LIB$PUT_OUTPUT routine, LIB-326 
LIB$RADIX_POINT routine, LIB-328 
LIB$REMQHI routine, LIB-330 
LIB$REMQTI routine, LIB-332 
LIB$RENAME_FILE routine, LIB-334 
LIB$RESERVE_EF routine, LIB-342 
LIB$RESET_VM_ZONE routine, LIB-344 
LIB$REVERT routine, LIB—346 
LIB$RUN_PROGRAM routine, LIB-347 
LIB$SCANC routine, LIB-349 
LIB$SCOPY_DXDX routine, LIB-351 
LIB$SCOPY_R_DX routine, LIB-353 
LIB$SET_LOGICAL routine, LIB-355 
LIB$SET_SYMBOL routine, LIB-359 
LIB$SFREE 1_DD routine, LIB-362 
LIB$SFREEN_DD routine, LIB-363 
LIB$SGET1_DD routine, LIB-365 
LIB$SHOW_TIMER routine, LIB-367 
LIB$SHOW_VM routine, LIB-371 
LIB$SHOW_VM_ZONE routine, LIB-374 
LIB$SIGNAL routine, LIB-380 
LIB$SIG_TO_RET routine, LIB-384 
LIB$SIG_TO_STOP routine, LIB-386 
LIB$SIM_TRAP routine, LIB-388 
LIB$SKPC routine, LIB-390 


LIB$SPANC routine, LIB-392 
LIB$SPAWN routine, LIB-396 
LIB$STAT_TIMER routine, LIB-402 
LIB$STAT_VM routine, LIB-406 
LIB$STOP routine, LIB—408 
LIB$SUBX routine, LIB-412 
LIB$SUB_TIMES routine, LIB-410 
LIB$SYS_ASCTIM routine, LIB-414 
LIB$SYS_FAOL routine, LIB-418 
LIB$SYS_FAO routine, LIB-416 
LIB$SYS_GETMSG routine, LIB-420 
LIB$TPARSE routine, LIB—423 
LIB$TRAVERSE_TREE routine, LIB-479 
LIB$TRA_ASC_EBC routine, LIB-472 
LIB$TRA_EBC_ASC routine, LIB-476 
LIB$TRIM_FILESPEC routine, LIB-481 
LIB$VERIFY_VM_ZONE routine, LIB—484 
LIB$WAIT routine, LIB-485 
Logical names, LIB—355 
RTL routines, LIB—112 
Logical unit numbers 

RTL routine to free, LIB—174 

M_ 

Mailboxes, LIB-12 

MATCHC (Match Characters) instruction 
RTL routine to access, LIB—276 
MOVC3 (Move Character 3 Operand) instruction 
RTL routine to access, LIB-281 
MOVC5 (Move Character 5 Operand) instruction 
RTL routine to access, LIB-283 
Multiplication, LIB—126, LIB-128, LIB—130, 
LIB-132 

extended precision, LIB—134 

o_ 

Octal text 

converting to binary, LIB—74 

P_ 

Polynomials 

evaluating, LIB-313, LIB-315, LIB-318, 
LIB-320 

Q_ 

Queues, LIB—258 

entry insertion, LIB—255 

R_ 

Reserved operands 

fix floating-point faults, LIB—162 
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Run-time library routines 
conversion, 1—7 
CVT$, 1-7 
library, 1-1 
translated, 1-6 

S_ 

SCANC (SCAN Characters) instruction 
RTL routine to access, LIB-349 


Shareable images 

activating, LIB-157 
Sign-Extended longword fields, LIB-140 
String descriptors, LIB-10 
Strings 

copying by descriptor, LIB-351 
copying by reference, LIB-353 
skipping characters in, LIB-393 
Subtraction 

quadword times, LIB—410 
two’s complement, LIB-413 
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How to Order Additional Documentation 


Technical Support 

If you need help deciding which documentation best meets your needs, call 800-DIGITAL (800-344-4825) 
and press 2 for technical assistance. 


Electronic Orders 

If you wish to place an order through your account at the Electronic Store, dial 800-234-1998, using a 
modem set to 2400- or 9600-baud. You must be using a VT terminal or terminal emulator set at 8 bits, no 
parity. If you need assistance using the Electronic Store, call 800-DIGITAL (800-344-4825) and ask for an 
Electronic Store specialist. 


Telephone and Direct Mail Orders 


From 


Call 


Write 


U.S.A. 


Puerto Rico 


Canada 


International 


Internal Orders 1 
(for software 
documentation) 


Internal Orders 
(for hardware 
documentation) 


DECdirect 

Phone: 800-DIGITAL 
(800-344-4825) 

FAX: (603) 884-5597 

Phone: (809) 781-0505 
FAX: (809) 749-8377 


Phone: 800-267-6215 
FAX: (613) 592-1946 


DTN: 241-3023 
(508) 874-3023 


DTN: 234-4325 
(508) 351-4325 
FAX: (508) 351-4467 


Digital Equipment Corporation 
P.O. Box CS2008 
Nashua, NH 03061 


Digital Equipment Caribbean, Inc. 

3 Digital Plaza, 1st Street 

Suite 200 

Metro Office Park 

San Juan, Puerto Rico 00920 

Digital Equipment of Canada Ltd. 
100 Herzberg Road 
Kanata, Ontario, Canada K2K 2A6 
Attn: DECdirect Sales 

Local Digital subsidiary or 
approved distributor 

Software Supply Business (SSB) 
Digital Equipment Corporation 
1 Digital Drive 
Westminster, MA 01473 

Publishing & Circulation Services 
Digital Equipment Corporation 
NR02-2 

444 Whitney Street 
Northboro, MA 01532 


1 Call to request an Internal Software Order Form (EN-01740-07). 
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